Azure OCR

​

Who is this for?

​

Prerequisites

• An Azure subscription with access to Azure AI services.
• A Computer Vision (or Multi-Service Cognitive) resource — for the image tool. From the Azure portal, under the resource’s Keys and Endpoint page, note its endpoint hostname (e.g. az-aismsa-xxx.cognitiveservices.azure.com) and one of its API keys.
• A Document Intelligence resource — for the document tool. Same Keys and Endpoint page: note the endpoint hostname (e.g. az-di-xxx.cognitiveservices.azure.com) and an API key.

context_id,agent_id,user_id

context_id,agent_id,user_id

You have access to the Azure OCR MCP server (tools: image, document). Each tool takes an `action: analyze` argument.
- image — for a single image (photo, screenshot, receipt picture). Pass the public image URL as `source`. Default feature is Read (OCR); add Caption, Tags, Objects or People only when the user asks for visual analysis. Synchronous.
- document — for PDFs and multi-page or structured documents. Pass a document URL (or base64 with sourceType: base64) as `source`, and pick the model by intent: prebuilt-read for plain text, prebuilt-layout for tables and structure, prebuilt-invoice / prebuilt-receipt / prebuilt-idDocument for those specific document types.
Prefer outputContentFormat: markdown when feeding the result back into your own reasoning. Always pass a public URL when you have one; base64 inflates the request.

{
  "name": "image",
  "arguments": {
    "action": "analyze",
    "source": "https://example.com/receipt.jpg",
    "features": "Read,Caption,Tags",
    "language": "fr"
  }
}

{
  "name": "document",
  "arguments": {
    "action": "analyze",
    "source": "https://example.com/invoice.pdf",
    "model": "prebuilt-invoice",
    "locale": "fr-FR",
    "outputContentFormat": "markdown"
  }
}

- Azure OCR.analyzeImage:
    source: '{{photo_url}}'
    features: Read
    language: fr
    output: ocr

- Azure OCR.analyzeDocument:
    source: https://example.com/invoice.pdf
    model: prebuilt-invoice
    locale: fr-FR
    outputContentFormat: markdown
    output: invoice

- Azure OCR.analyzeDocument:
    source: '{{pdf_base64}}'
    sourceType: base64
    model: prebuilt-layout
    pages: 1-3
    output: layout

- Azure OCR.analyzeDocument:
    source: '{{scan_base64}}'
    sourceType: base64
    model: prebuilt-idDocument
    output: id
- conditions:
    '{{id.error}}':
      - emit:
          event: id.ocr.failed
          payload: '{{id}}'
    default:
      - emit:
          event: id.parsed
          payload: '{{id}}'

​

Error Handling

{
  "error": "ConfigurationError | ValidationError | NetworkError | AzureError | Unauthorized | Forbidden | NotFound | RateLimited | ServerError | ProcessingFailed | Timeout",
  "message": "Human-readable explanation",
  "details": {
    "service": "computervision | documentIntelligence",
    "automation": "analyzeImage | analyzeDocument",
    "status": 401,
    "body": {}
  }
}

​

Common Issues

• “This agent is not authorized to use this connector” — The calling agent is not in the allowlist. Open the configuration app → Authorized agents → tick this agent (or enable Allow all agents) and Save. The Install capability button does this for you.
• “The calling agent could not be identified” — The MCP capability Scope does not declare agent_id, so Agent Factory never injects the agent identity. Set the Scope to context_id,agent_id,user_id on the capability, then allow the agent in the config app.
• ConfigurationError (”… is not configured”) — The targeted service has no endpoint or API key in the connector configuration. Each workspace must paste its own Azure endpoint and key in the config app; there is no platform-level credential to fall back on. Configure only the service(s) you call.
• Unauthorized (401, invalid key) — Azure rejected the key. Regenerate or copy a current key from the resource’s Keys and Endpoint page, and confirm it matches the service you are calling (Computer Vision keys do not work on Document Intelligence and vice versa).
• Forbidden (403, API not enabled) — The key is valid but the resource does not expose the requested API. Confirm the resource type (a Document Intelligence key cannot serve Image Analysis) and that the feature is enabled on the Azure resource.
• NetworkError / NotFound (404, bad endpoint) — Almost always a malformed endpoint. Store the hostname only (no https://, no path); the connector strips a leading scheme and trailing slash but cannot recover a wrong host.
• Timeout on document — Document Intelligence is asynchronous: the connector submits the document, then polls for up to 60s. Long or heavy PDFs can exceed this limit. Reduce pages, switch to the lighter prebuilt-read model, or split the document upstream.
• Service-specific gotcha — image is synchronous and document is an async submit-and-poll cycle handled internally; both return their error payload instead of raising. After a DSUL call, always branch on {{result.error}} — a failed extraction is a normal value, not an exception, so a missing check silently passes the error object downstream.

​

External Resources