MCP Integration

MedRAG provides a remote MCP (Model Context Protocol) endpoint that lets LLM agents query your medical knowledge bases directly. Your agent connects over HTTP — no local installation.

Availability

The MCP endpoint is https://medrag.eu/mcp/sse (with https://medrag.eu/mcp/message for tool calls). It does not accept API keys; it accepts OAuth access tokens only.

How Authentication Works

MedRAG’s authorization server issues short-lived access tokens (15 minutes):

1. Your OAuth application is registered by MedRAG support, which gives you a client_id and a client_secret
2. Your agent requests a token from https://medrag.eu/oauth/token using the client_credentials grant
3. Your agent sends the token as Authorization: Bearer <token> to the MCP endpoint
4. Without a valid token the endpoint answers 401 with a WWW-Authenticate header

Interactive sign-in for desktop AI clients (browser login with your MedRAG account, tokens managed by the client) is in development. Until it ships, adding the MedRAG URL to a desktop client’s MCP configuration will not work.

The client_secret is a credential: keep it in your CI system’s secrets manager, never in version control.

Enterprise: Backend Agents & CI/CD

Enterprise customers running automated agents (CI/CD pipelines, server-to-server integrations) that cannot open a browser can use OAuth Client Credentials:

1. Register an OAuth Application

Coming soon. Self-service OAuth application management (create/view/revoke) will be available in the MedRAG web portal under Settings → OAuth Applications.

In the meantime, contact support to register an OAuth application for your tenant. You’ll receive a client_id and client_secret.

Store the secret securely (e.g., in your CI system’s secrets manager).

2. Obtain an Access Token

Your agent requests a short-lived token:

curl -X POST https://medrag.eu/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=medrag_client_xxxx" \
  -d "client_secret=$MEDRAG_CLIENT_SECRET" \
  -d "scope=mcp:read"

Response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "mcp:read"
}

The token expires in 15 minutes. Your agent should request a new one before expiry.

3. Connect to the MCP Endpoint

# SSE connection with Bearer token
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Accept: text/event-stream" \
     https://medrag.eu/mcp/sse

Or send individual tool calls:

curl -X POST https://medrag.eu/mcp/message \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "medrag_query",
      "arguments": {"query": "blood pressure targets", "top_k": 5}
    },
    "session_id": "<session_id_from_sse>"
  }'

Sub-Tenant Scoping (Enterprise)

If your OAuth application is scoped to a specific sub-tenant, the access token will only grant access to that sub-tenant’s knowledge bases. This ensures data isolation across your hospitals or organisations.

Available Tools

medrag_query

Semantic search across your knowledge bases.

medrag_list_knowledge_bases

List available knowledge bases. Returns ID, name, and document count for each.

No parameters required.

How It Works

1. Your AI client discovers MedRAG’s tools via MCP tools/list at connection time
2. When the user asks a question that could benefit from medical knowledge retrieval, the agent decides to call medrag_query
3. MedRAG returns scored chunks with source document references
4. The agent uses the retrieved information to ground its answer

The agent decides when to call MedRAG based on the tool description and user’s question — just like any other MCP tool.

Security

• No secrets in config: The only thing in your MCP config is a URL
• Short-lived tokens: Access tokens expire in 15 minutes; refresh is automatic
• Scope control: Request only the permissions your agent needs
• Tenant isolation: Each token is scoped to your tenant; cross-tenant access is impossible
• Sub-tenant isolation (Enterprise): Tokens can be further restricted to specific sub-tenants