MCP Server

The Invox Medical MCP Server lets your AI client (Claude Code, Codex, Cursor, VS Code or any other client that supports the Model Context Protocol) search and read this documentation while you build your integration.

  • Read-only
  • Published documentation only
  • No patient data
  • No audio processing
  • No sandbox

The server is read-only and only serves the published documentation. It does not read or write patient data, and it uses your credential only to validate it against the Invox token endpoint; it does not call any other Invox API. It does not transcribe or process audio, and it has no sandbox where you can run requests: to try the APIs, use your own credentials against the API itself.

On this page

Server URL

The server uses the Streamable HTTP transport:

text
https://mcp.invoxmedical.com

Credentials

Every request must carry your integration credentials in an Authorization: Basic header. Get your APP Id and API Key as described in Credentials.

Security

  • Use a dedicated credential for the MCP Server, with no more permissions than it needs. The MCP Server does not need any API permission, because it only serves documentation.
  • Do not paste patient data into the conversations of your AI client.
  • Do not share your API Key: keep it out of shared files and repositories.

Define your APP Id and API Key as environment variables, and calculate the token from them. The token is the Base64 encoding of APP Id:API Key:

INVOX_APP_ID<your-app-id>
plus
INVOX_API_KEY<your-api-key>
gives
INVOX_MCP_TOKENBase64 of APP Id:API Key
bash
export INVOX_APP_ID="<your-app-id>"
export INVOX_API_KEY="<your-api-key>"
export INVOX_MCP_TOKEN="$(printf '%s:%s' "$INVOX_APP_ID" "$INVOX_API_KEY" | base64 | tr -d '\n')"
powershell
$env:INVOX_APP_ID = "<your-app-id>"
$env:INVOX_API_KEY = "<your-api-key>"
$env:INVOX_MCP_TOKEN = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("$($env:INVOX_APP_ID):$($env:INVOX_API_KEY)"))

Start your AI client from the same terminal, so that it inherits the variables. On Windows, with a window of the client already open, a new window opened with its executable or its shortcut does not receive the variables, even if you open it from that terminal. Close every window of the client first and start it again from that terminal. In VS Code you can instead open the folder in a new window with code <folder> from that terminal. In Cursor, close all the Cursor windows and open it again from that terminal.

Client configuration

Each block reads the token from the INVOX_MCP_TOKEN environment variable, so the token never goes into the file. Save the block in the file of your client: .mcp.json in your project root for Claude Code, ~/.codex/config.toml for Codex, .cursor/mcp.json for Cursor, .vscode/mcp.json for VS Code.

.mcp.json
{
  "mcpServers": {
    "invox-medical": {
      "type": "http",
      "url": "https://mcp.invoxmedical.com",
      "headers": {
        "Authorization": "Basic ${INVOX_MCP_TOKEN}"
      }
    }
  }
}
~/.codex/config.toml
[mcp_servers.invox-medical]
url = "https://mcp.invoxmedical.com"
env_http_headers = { "Authorization" = "INVOX_MCP_AUTH" }

Codex sends the value of INVOX_MCP_AUTH as the whole header, so define it with the Basic prefix: export INVOX_MCP_AUTH="Basic $INVOX_MCP_TOKEN" (PowerShell: $env:INVOX_MCP_AUTH = "Basic $env:INVOX_MCP_TOKEN"). codex mcp add cannot set this header: edit the file. Do not use --bearer-token-env-var: it sends a Bearer token and the server only accepts Basic.

.cursor/mcp.json
{
  "mcpServers": {
    "invox-medical": {
      "url": "https://mcp.invoxmedical.com",
      "headers": {
        "Authorization": "Basic ${env:INVOX_MCP_TOKEN}"
      }
    }
  }
}
.vscode/mcp.json
{
  "servers": {
    "invox-medical": {
      "type": "http",
      "url": "https://mcp.invoxmedical.com",
      "headers": {
        "Authorization": "Basic ${env:INVOX_MCP_TOKEN}"
      }
    }
  }
}
json
{
  "mcpServers": {
    "invox-medical": {
      "url": "https://mcp.invoxmedical.com",
      "headers": {
        "Authorization": "Basic ${INVOX_MCP_TOKEN}"
      }
    }
  }
}

For the generic block, replace ${INVOX_MCP_TOKEN} with your client's environment-variable syntax; never paste the token into a shared file.

With Claude Code you can also add the server from the command line. The token value is then stored in the Claude Code configuration:

bash
claude mcp add --transport http invox-medical https://mcp.invoxmedical.com --header "Authorization: Basic $INVOX_MCP_TOKEN"

Approve the server

Cursor and Claude Code do not use a server saved in the project until you approve it. In Cursor, the server stays Disabled until you turn it on in Customize > MCPs. In Claude Code, claude mcp list shows Pending approval until you approve the server inside claude.

If your credential belongs to an organization

Skip this step if your credential has no organization: the blocks above are all you need. Add the header if your credential belongs to an organization: Invox will require it, and sending a well-formed value before that does no harm.

The X-Invox-Medical-Organization-Id header carries the subdomain of your organization: the same value you pass as organizationId to INVOX.init (see Credentials). It has 1 to 100 lowercase letters, digits and single hyphens. It is not the organization UUID.

Define the value as an environment variable, in the same terminal where you defined the others:

bash
export INVOX_ORGANIZATION_ID="<your-organization-subdomain>"
powershell
$env:INVOX_ORGANIZATION_ID = "<your-organization-subdomain>"

Then add the header to the configuration of your client. Each block is the base block with the header added. In Codex, add it to the existing env_http_headers; do not repeat the key:

.mcp.json
{
  "mcpServers": {
    "invox-medical": {
      "type": "http",
      "url": "https://mcp.invoxmedical.com",
      "headers": {
        "Authorization": "Basic ${INVOX_MCP_TOKEN}",
        "X-Invox-Medical-Organization-Id": "${INVOX_ORGANIZATION_ID}"
      }
    }
  }
}
~/.codex/config.toml
[mcp_servers.invox-medical]
url = "https://mcp.invoxmedical.com"
env_http_headers = { "Authorization" = "INVOX_MCP_AUTH", "X-Invox-Medical-Organization-Id" = "INVOX_ORGANIZATION_ID" }

Codex sends the value of INVOX_ORGANIZATION_ID as the whole header, so it needs no prefix.

.cursor/mcp.json
{
  "mcpServers": {
    "invox-medical": {
      "url": "https://mcp.invoxmedical.com",
      "headers": {
        "Authorization": "Basic ${env:INVOX_MCP_TOKEN}",
        "X-Invox-Medical-Organization-Id": "${env:INVOX_ORGANIZATION_ID}"
      }
    }
  }
}
.vscode/mcp.json
{
  "servers": {
    "invox-medical": {
      "type": "http",
      "url": "https://mcp.invoxmedical.com",
      "headers": {
        "Authorization": "Basic ${env:INVOX_MCP_TOKEN}",
        "X-Invox-Medical-Organization-Id": "${env:INVOX_ORGANIZATION_ID}"
      }
    }
  }
}
json
{
  "mcpServers": {
    "invox-medical": {
      "url": "https://mcp.invoxmedical.com",
      "headers": {
        "Authorization": "Basic ${INVOX_MCP_TOKEN}",
        "X-Invox-Medical-Organization-Id": "${INVOX_ORGANIZATION_ID}"
      }
    }
  }
}

In the generic block, replace ${INVOX_ORGANIZATION_ID} with your client's environment-variable syntax.

With the Claude Code command line, add a second --header:

bash
claude mcp add --transport http invox-medical https://mcp.invoxmedical.com --header "Authorization: Basic $INVOX_MCP_TOKEN" --header "X-Invox-Medical-Organization-Id: $INVOX_ORGANIZATION_ID"

Undefined variable in Claude Code and Cursor

If INVOX_ORGANIZATION_ID is not defined when the client starts, Claude Code and Cursor do not replace ${INVOX_ORGANIZATION_ID} (in Cursor, ${env:INVOX_ORGANIZATION_ID}): they send that text as the header value and the server answers Invalid credentials. Codex omits the header instead, and VS Code does not send the text: in both cases the request goes without an organization. Define the variable and start the client again.

Available tools

The server offers 12 tools. All of them are read-only.

ToolUse it to
search_docsSearch the documentation and get the matching pages with an excerpt.
get_doc_pageRead one documentation page as Markdown.
get_sdk_referenceFind the Dictation SDK page of a class, method or topic.
list_endpointsList the endpoints that exist in one API version.
get_endpoint_referenceRead the contract of one endpoint: method, path, permission, schemas, errors and examples.
compare_api_versionsSee what changes between two API versions.
get_webhook_eventRead the fields and the signature order of a webhook event.
explain_errorFind the cause and the fix of an error from its HTTP status and error type.
validate_requestCheck a request body against the contract of an endpoint without sending it.
get_integration_recipeRead the step-by-step recipe of an integration flow.
get_code_sampleRead the official code sample of an endpoint or of an integration recipe.
check_credentialsCheck that your credential is valid and which permissions it grants.

Integration recipes

The MCP Server offers one guided recipe for each of these integration flows:

  • Batch Transcription API Guide
  • Clinical note generation
  • Get started with the Dictation SDK
  • Onboard a user into your organization
  • SOFT Integration
  • Streaming guide
  • Webhooks

Troubleshooting

credentials_required

The server checks your credentials on the first tool call or the first read of a resource that needs credentials, not when the client connects (unless the client sends no header at all): tools are listed but every call except check_credentials returns credentials_required if the credentials are wrong. A successful connection does not prove that your credentials are valid. Call check_credentials to find out whether they are valid, which permissions they grant and when the access token that the server gets with them expires. With wrong credentials it answers valid: false with Invalid credentials as the reason, or Invalid authorization header if the token is malformed. A change of credentials or permissions can take up to 2 hours to show.

Missing credentials

The client sent no Authorization header, and the error appears as soon as it connects. Check that your client supports headers in its MCP configuration.

Invalid authorization header

The token is not the Base64 of APP Id:API Key (for example, it contains a line break), or the INVOX_MCP_TOKEN variable is not defined. In Claude Code, an undefined variable is not replaced: the client sends the text Basic ${INVOX_MCP_TOKEN} as is, and the server rejects it with this error. Claude Code warns you before: claude mcp list shows Missing environment variables: INVOX_MCP_TOKEN. Define the variable and calculate the token again with the command above. In Codex, --bearer-token-env-var sends Bearer <token>: use env_http_headers with the Basic prefix instead.

Invalid credentials

The token is well formed but the APP Id or the API Key is incorrect. It also appears when your credential belongs to an organization and the X-Invox-Medical-Organization-Id header is missing or from a different organization, when Invox requires it for your environment. A malformed value always gives it, whatever the environment. The answer does not say which of these happened. In Claude Code and Cursor, an undefined ${INVOX_ORGANIZATION_ID} (${env:INVOX_ORGANIZATION_ID} in Cursor) is sent as that literal text, which is malformed. See If your credential belongs to an organization.

If you opened your AI client before defining the variables, close it and start it again from a terminal where they are defined: the client only reads its environment when it starts.

In Cursor and VS Code, an undefined INVOX_MCP_TOKEN does not stop the connection: the client connects and lists the tools, and every call answers Invalid authorization header. Define the variable and start the client again from that terminal.

rate_limited

The server answers with HTTP 429 and a Retry-After header when your application sends too many requests per minute, or when the same client makes too many credential checks per minute. Wait the number of seconds that Retry-After indicates before you call again; an earlier call is rejected again.

request_blocked

The server answers with HTTP 403 and this body when the edge firewall blocked the request body, for example because it contains <script> markup:

json
{"error":{"code":-32001,"message":"request_blocked","data":{"reason":"Request body blocked by the edge firewall"}}}

Send the request again without that content in the body.