Skip to content

MCP Connectors

OpenMed can discover remote MCP servers and expose their tools inside the same agent loop as the native tool registry. MCP is optional, user-configured, and separate from the built-in 62 native tools.

No MCP servers are configured by default.

Native vs MCP

These capabilities already ship natively and do not require MCP:

  • extraction and PII tooling such as extract_entities, extract_pii, and deidentify_text
  • terminology and literature tools such as search_pubmed, search_icd10_codes, lookup_cpt_code, lookup_snomed_code, and HCC helpers
  • deterministic workflows
  • built-in skills

Use MCP for external systems that are not already part of the native OpenMed surface, such as internal policy services, registries, payer tools, institutional knowledge hubs, or other organization-specific systems.

Configuration file

Default path:

~/.config/openmed/mcp_servers.json

Override it with:

export OPENMED_MCP_CONFIG_PATH=/path/to/mcp_servers.json

OpenMed bootstraps the file automatically on first MCP-aware CLI or TUI use.

Schema:

{
  "version": 1,
  "servers": [
    {
      "id": "guidelines_hub",
      "name": "Guidelines Hub",
      "url": "https://example.com/mcp",
      "enabled": true,
      "timeout_seconds": 20,
      "extra_headers": {}
    }
  ]
}

Current validation rules:

  • url must be HTTPS
  • id must start with a letter and use lowercase letters, digits, or underscores
  • timeout_seconds must be between 1 and 120

CLI management

openmed mcp list
openmed mcp add guidelines_hub https://example.com/mcp --name "Guidelines Hub"
openmed mcp enable guidelines_hub
openmed mcp disable guidelines_hub
openmed mcp enable --all
openmed mcp disable --all
openmed mcp set-url guidelines_hub https://new-url.example.com/mcp
openmed mcp remove guidelines_hub
openmed mcp doctor
openmed mcp doctor --all
openmed mcp doctor guidelines_hub

doctor is the quickest way to confirm that a URL is actually a live JSON-RPC MCP endpoint rather than a marketing page or docs site.

Environment overrides

For a server ID such as guidelines_hub, OpenMed checks:

  • OPENMED_MCP_GUIDELINES_HUB_ENABLED
  • OPENMED_MCP_GUIDELINES_HUB_URL
  • OPENMED_MCP_GUIDELINES_HUB_HEADERS_JSON

Example:

export OPENMED_MCP_GUIDELINES_HUB_ENABLED=true
export OPENMED_MCP_GUIDELINES_HUB_URL=https://example.com/mcp
export OPENMED_MCP_GUIDELINES_HUB_HEADERS_JSON='{"Authorization":"Bearer ..."}'

How MCP tools appear

Discovered remote tools are namespaced as:

mcp__<server_id>__<tool_name>

They are registered as remote ToolDefinition entries during discovery.

Discovery and caching

MCP discovery is lazy rather than happening on package import.

Current cache behavior:

  • cache file: ~/.config/openmed/mcp_tools_cache.json
  • override path: OPENMED_MCP_TOOLS_CACHE_PATH
  • override TTL: OPENMED_MCP_TOOLS_CACHE_TTL_SECONDS

The cache exists to reduce repeated startup/discovery overhead when MCP is enabled.

TUI usage

In the TUI:

  • type # to browse enabled MCP namespaces
  • run /mcp to inspect configured servers, URLs, enabled state, and discovered-tool counts

If openmed mcp doctor reports that a server returned HTML, the configured URL is not the live MCP JSON-RPC endpoint.

Boundary notes

MCP is an extension surface, not a replacement for the native tool inventory.

Important trust boundary notes:

  • remote MCP servers are user-configured and open-ended, so they are not counted in the built-in 62 native tools
  • MCP tool definitions may carry metadata such as requires_phi_gate, but that metadata is not a substitute for your own deployment, policy, or compliance controls
  • once you add a remote MCP server, its network, auth, retention, and privacy behavior become part of your real system boundary

OpenMed currently lets users add MCP servers and local skills, but it does not yet expose a public CLI for registering brand-new native medical backends.