oth-mcp

MCP server for https://doccla-dev.oth.io/api/docs Gives agents direct access to query and manage OTH resources

https://github.com/user-attachments/assets/c31f864a-2896-46b2-8ac1-ae62dd9293b5

Design

The server is designed for minimal token usage. Instead of embedding the full API reference in tool descriptions, the endpoint guide is exposed as an MCP resource (oth://api-guide) that the agent loads on demand — only when it needs to look up paths or request bodies. This keeps each tool call lightweight while still giving agents access to the complete reference.

Setup

Defaults with no env set: OTH_ENV=dev → base URL https://doccla-dev.oth.io, credentials read from Keychain account oth-dev. Override OTH_ENV (dev, stag, demo, local) to target another environment — the Keychain account name follows as oth-<env>.

1. Configure credentials

macOS Keychain (preferred) — no plaintext on disk:

# Account name is oth-<env>, so repeat per env you use
# (oth-dev, oth-stag, oth-demo, oth-local):
security add-generic-password -a "oth-dev" -s "oth-mcp-username" -w
security add-generic-password -a "oth-dev" -s "oth-mcp-password" -w

Environment variables (works everywhere):

export OTH_USERNAME="your-username"
export OTH_PASSWORD="your-password"
export OTH_ENV="dev"  # optional, defaults to dev

2. Add to Claude Code (no env default dev)

claude mcp add oth -- npx -y oth-mcp

Pass env vars with -e KEY=VALUE (repeatable). Example pointing at a local opentele stack with inline creds:

claude mcp add oth \
  -e OTH_ENV=local \
  -e OTH_USERNAME=admin \
  -e OTH_PASSWORD=admin_23 \
  -- npx -y oth-mcp

Omit OTH_USERNAME/OTH_PASSWORD if you've stored them in Keychain under oth-local. Use -e OTH_BASE_URL=http://host.docker.internal:7100 if the default http://localhost:7100 isn't reachable.

Local OTH (docker)

To point the MCP at a local opentele stack run via docker:

# in the opentele repo:
cd dev && docker compose up -d --wait

# then launch the MCP with:
export OTH_ENV=local          # → http://localhost:7100
export OTH_USERNAME=admin
export OTH_PASSWORD=admin_23  # or any dev account — see opentele docs

Or store local creds in Keychain under the oth-local account:

security add-generic-password -a "oth-local" -s "oth-mcp-username" -w
security add-generic-password -a "oth-local" -s "oth-mcp-password" -w

Set OTH_BASE_URL to override the host/port (e.g. http://host.docker.internal:7100) if you're not on the default.

Tools

oth_get

GET any OTH API endpoint. Common paths are listed in the tool description; read the oth://api-guide resource for the full reference.

oth_get({ path: "/clinician/api/patients", query: { max: "10" } })

oth_mutate

POST, PUT, PATCH, or DELETE to any OTH API endpoint.

oth_mutate({ method: "POST", path: "/clinician/api/patient-notes", body: { note: "Test", type: "normal", links: { patient: "https://doccla-dev.oth.io/clinician/api/patients/123" } } })

oth_env

Switch environment or check current state.

oth_env({ environment: "stag" })
oth_env({})  // show current env + auth state

Limitations

• MFA not supported — accounts with MFA enabled will fail to authenticate. Use an account without MFA.
• macOS Keychain only on macOS — Linux/Windows users must use environment variables.