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:
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:
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')"
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.
{
"mcpServers": {
"invox-medical": {
"type": "http",
"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:
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:
export 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:
{
"mcpServers": {
"invox-medical": {
"type": "http",
"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:
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.
| Tool | Use it to |
|---|---|
search_docs | Search the documentation and get the matching pages with an excerpt. |
get_doc_page | Read one documentation page as Markdown. |
get_sdk_reference | Find the Dictation SDK page of a class, method or topic. |
list_endpoints | List the endpoints that exist in one API version. |
get_endpoint_reference | Read the contract of one endpoint: method, path, permission, schemas, errors and examples. |
compare_api_versions | See what changes between two API versions. |
get_webhook_event | Read the fields and the signature order of a webhook event. |
explain_error | Find the cause and the fix of an error from its HTTP status and error type. |
validate_request | Check a request body against the contract of an endpoint without sending it. |
get_integration_recipe | Read the step-by-step recipe of an integration flow. |
get_code_sample | Read the official code sample of an endpoint or of an integration recipe. |
check_credentials | Check 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:
{"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.