MCP Agents

Connect AI assistants to Patient Journey Intelligence using the Model Context Protocol (MCP) for standardized, secure access to medical tools and patient data.

Plug Healthcare Data into Any MCP-Compatible AI

Use Claude Desktop, custom MCP clients, or any MCP-compatible system to access clinical NLP, terminology servers, and patient data through a standardized protocol.

What is MCP?

Model Context Protocol (MCP) is an open standard developed by Anthropic that enables AI assistants to securely connect to external tools and data sources. Think of it as "USB for AI" – a universal interface that lets any MCP-compatible client (like Claude Desktop) access any MCP-compatible server.

Benefits for Healthcare AI:

Standardization: One protocol works across all MCP-compatible tools and clients
Security: Built-in authentication, encryption, and audit logging
Composability: Mix and match tools from different providers
Maintainability: Update tools independently without changing client code

Architecture

🏗️ MCP Architecture Overview

Three-Layer Architecture:

MCP Client

→

Claude Desktop, Custom Apps, or Any MCP-Compatible AI

Sends requests to MCP servers using standardized protocol

MCP Protocol

→

JSON-RPC 2.0 over stdio or HTTP/SSE

Handles tool discovery, invocation, and result streaming

MCP Server

→

Patient Journey Intelligence Platform

Exposes clinical NLP, terminology, and patient data as MCP tools

Setting Up MCP with Claude Desktop

Step 1: Install Claude Desktop

Download Claude Desktop from claude.ai/desktop (macOS or Windows).

Step 2: Configure MCP Server Connection

Create or edit the Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Patient Journey Intelligence MCP server:

{
  "mcpServers": {
    "patient-journey": {
      "command": "npx",
      "args": [
        "-y",
        "@johnssnowlabs/mcp-server-patient-journey"
      ],
      "env": {
        "PJI_API_KEY": "your-api-key-here",
        "PJI_API_URL": "https://your-instance.patient-journey.ai/api"
      }
    }
  }
}

Step 3: Restart Claude Desktop

Close and reopen Claude Desktop. You should see a 🔨 (hammer) icon indicating MCP tools are available.

Step 4: Test the Connection

In Claude Desktop, try:

"What MCP tools are available?"

Claude should list the Patient Journey Intelligence tools like extract_clinical_entities, search_terminology, query_patient_data, etc.

Available MCP Tools

The Patient Journey Intelligence MCP server exposes the following tools. See the MCP Tools page for detailed schemas and examples.

🔍

extract_clinical_entities

Clinical NLP Extraction

Extract diagnoses, medications, procedures, lab results, and other clinical entities from free-text notes

📚

search_terminology

Medical Terminology Lookup

Search SNOMED CT, RxNorm, LOINC, ICD-10, and other standard terminologies for codes and descriptions

👤

query_patient_data

OMOP CDM Queries

Query patient demographics, conditions, medications, procedures, and observations from the OMOP CDM

🧬

build_cohort

Patient Cohort Builder

Define inclusion/exclusion criteria to identify patient populations for research or quality measurement

💊

check_drug_interactions

Drug Interaction Checker

Identify potential adverse interactions between medications using RxNorm and clinical databases

📊

calculate_clinical_measure

Quality Measure Calculator

Calculate HEDIS, CMS, and custom quality measures for patient populations

Example Agent Workflows

Example 1: Extract and Code Diagnoses

User Prompt in Claude Desktop:

"Here's a clinical note:\n\n'Patient presents with acute exacerbation of COPD. Currently experiencing increased dyspnea and productive cough with green sputum. No fever. Lung exam reveals diffuse wheezing bilaterally.'\n\nExtract the diagnoses and find their ICD-10 codes."

Claude's Tool Usage:

Calls extract_clinical_entities on the note text
Receives: ["COPD exacerbation", "dyspnea", "productive cough"]
Calls search_terminology for each diagnosis to find ICD-10 codes
Returns formatted results:

Diagnoses and ICD-10 Codes:
- COPD exacerbation → J44.1 (Chronic obstructive pulmonary disease with acute exacerbation)
- Dyspnea → R06.00 (Dyspnea, unspecified)
- Productive cough → R05.9 (Cough, unspecified)

Example 2: Check Drug Interactions

User Prompt:

"A patient is taking warfarin 5mg daily. The physician wants to add ibuprofen 400mg TID for back pain. Are there any interactions?"

Claude's Tool Usage:

Calls check_drug_interactions with medications: ["warfarin", "ibuprofen"]
Receives interaction alert:

{
  "severity": "major",
  "description": "NSAIDs like ibuprofen may increase anticoagulant effect of warfarin, increasing bleeding risk",
  "recommendation": "Consider alternative analgesic (e.g., acetaminophen) or monitor INR closely if ibuprofen is necessary"
}

Returns clear explanation to user with clinical recommendation

Example 3: Build Research Cohort

User Prompt:

"I need to identify all patients diagnosed with Type 2 Diabetes between 2020-2023 who are currently on metformin and have an HbA1c > 8% in the last 3 months."

Claude's Tool Usage:

Calls build_cohort with criteria:

{
  "inclusion": [
    {"condition": "Type 2 Diabetes", "date_range": "2020-01-01 to 2023-12-31"},
    {"medication": "metformin", "status": "active"},
    {"observation": "HbA1c", "value": ">8%", "date_range": "last 3 months"}
  ]
}

Receives cohort ID and patient count: {"cohort_id": "cohort_12345", "patient_count": 247}
Returns summary and offers to export or analyze the cohort further

Custom MCP Client Development

You can build your own MCP clients to integrate Patient Journey Intelligence into custom applications.

Python Example

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Connect to Patient Journey Intelligence MCP server
server_params = StdioServerParameters(
    command="npx",
    args=["-y", "@johnssnowlabs/mcp-server-patient-journey"],
    env={
        "PJI_API_KEY": "your-api-key",
        "PJI_API_URL": "https://your-instance.patient-journey.ai/api"
    }
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # Initialize connection
        await session.initialize()

        # List available tools
        tools = await session.list_tools()
        print(f"Available tools: {[tool.name for tool in tools]}")

        # Extract clinical entities from a note
        result = await session.call_tool(
            "extract_clinical_entities",
            arguments={
                "text": "Patient diagnosed with hypertension and started on lisinopril 10mg daily.",
                "entity_types": ["PROBLEM", "DRUG"]
            }
        )

        print(f"Extracted entities: {result.content}")

TypeScript Example

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

// Create transport to MCP server
const transport = new StdioClientTransport({
  command: "npx",
  args: ["-y", "@johnssnowlabs/mcp-server-patient-journey"],
  env: {
    PJI_API_KEY: "your-api-key",
    PJI_API_URL: "https://your-instance.patient-journey.ai/api"
  }
});

// Create client and connect
const client = new Client({
  name: "custom-healthcare-agent",
  version: "1.0.0"
}, {
  capabilities: {}
});

await client.connect(transport);

// Search medical terminology
const result = await client.callTool({
  name: "search_terminology",
  arguments: {
    query: "diabetes mellitus",
    terminology: "SNOMED_CT",
    limit: 5
  }
});

console.log("Search results:", result.content);

Authentication & Security

🔑 API Key Authentication

MCP server authenticates to platform using API keys with configurable permissions (read-only, read-write, admin)

🔒 Encrypted Transport

All data between MCP client and server is encrypted using TLS 1.3 for HTTP/SSE transport or OS-level security for stdio

📜 Audit Logging

Every tool invocation is logged with user ID, timestamp, input parameters, and results for compliance and debugging

🚫 PHI Filtering

Automatic PHI detection and redaction can be enabled for all tool outputs to prevent accidental PHI exposure

Troubleshooting

Connection Issues

Problem: Claude Desktop shows "Failed to connect to MCP server"

Solutions:

Verify PJI_API_KEY is correct in claude_desktop_config.json
Check PJI_API_URL points to your instance (no trailing slash)
Ensure you have network access to the platform
Check Claude Desktop logs: ~/Library/Logs/Claude/mcp*.log (macOS)

Tool Not Found

Problem: Claude says "I don't have access to that tool"

Solutions:

Restart Claude Desktop after config changes
Verify tool name matches exactly (case-sensitive)
Check MCP server logs for initialization errors
Run npx @johnssnowlabs/mcp-server-patient-journey --version to verify package installation

Slow Response Times

Problem: Tool calls take longer than expected

Solutions:

For large datasets, use pagination parameters to limit result size
Consider caching frequently-used terminology lookups
Check network latency to platform instance
Use async/streaming responses for long-running operations

MCP vs REST API

When to use MCP:

Building conversational AI agents (like Claude Desktop integrations)
Rapid prototyping with automatic tool discovery
Non-technical users need to access platform features through natural language
You want to leverage Claude's reasoning capabilities with your data

When to use REST API:

Building production web applications or mobile apps
Need fine-grained control over HTTP requests/responses
Integrating with existing non-MCP systems
Batch processing or scheduled jobs

See Platform REST API for HTTP endpoint documentation.

Best Practices

💡 MCP Agent Development Tips

Start simple: Test individual tools in Claude Desktop before building complex multi-tool workflows
Handle errors gracefully: Tools may return errors for invalid inputs or system issues – design agents to retry or fallback
Use specific entity types: When extracting entities, specify exact types (e.g., "PROBLEM", "DRUG") for better accuracy
Cache terminology lookups: Medical codes rarely change – cache results to reduce API calls
Test with diverse data: Validate agents on different note types, documentation styles, and edge cases
Monitor token usage: Clinical notes can be long – track Claude's token consumption to manage costs

Next Steps

MCP Tools Catalog Medical LLM & VLM Platform REST API Building Agents Overview

Plug Healthcare Data into Any MCP-Compatible AI

What is MCP?​

Architecture​

🏗️ MCP Architecture Overview

Setting Up MCP with Claude Desktop​

Step 1: Install Claude Desktop​

Step 2: Configure MCP Server Connection​

Step 3: Restart Claude Desktop​

Step 4: Test the Connection​

Available MCP Tools​

extract_clinical_entities

search_terminology

query_patient_data

build_cohort

check_drug_interactions

calculate_clinical_measure

Example Agent Workflows​

Example 1: Extract and Code Diagnoses​

Example 2: Check Drug Interactions​

Example 3: Build Research Cohort​

Custom MCP Client Development​

Python Example​

TypeScript Example​

Authentication & Security​

🔑 API Key Authentication

🔒 Encrypted Transport

📜 Audit Logging

🚫 PHI Filtering

Troubleshooting​

Connection Issues​

Tool Not Found​

Slow Response Times​

MCP vs REST API​

Best Practices​

💡 MCP Agent Development Tips

Next Steps​

What is MCP?

Architecture

Setting Up MCP with Claude Desktop

Step 1: Install Claude Desktop

Step 2: Configure MCP Server Connection

Step 3: Restart Claude Desktop

Step 4: Test the Connection

Available MCP Tools

Example Agent Workflows

Example 1: Extract and Code Diagnoses

Example 2: Check Drug Interactions

Example 3: Build Research Cohort

Custom MCP Client Development

Python Example

TypeScript Example

Authentication & Security

Troubleshooting

Connection Issues

Tool Not Found

Slow Response Times

MCP vs REST API

Best Practices

Next Steps