MCP Server

Ignixa includes an experimental Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with FHIR data directly.

:::caution Experimental Feature MCP support is experimental and may change in future releases. :::

Overview

The MCP server exposes FHIR operations as tools that AI assistants can invoke. This enables natural language interactions like:

• "Find all patients named Smith"
• "Show me the latest observations for patient 123"
• "Update the patient's phone number"
• "Install the US Core implementation guide"

Configuration

Enable MCP in appsettings.json:

{
  "Experimental": {
    "Enabled": true,
    "Features": {
      "Mcp": {
        "Enabled": true,
        "Transport": "http"
      }
    }
  }
}

Default: Enabled (when Experimental:Enabled is true)

Endpoint

The MCP server is accessible at:

POST /mcp

This endpoint uses MCP Streamable HTTP transport for bidirectional streaming with AI clients like Claude.

Available Tools

FHIR Operations

search_fhir_resources

Search for FHIR resources with LLM-optimized response sizes.

{
  "name": "search_fhir_resources",
  "arguments": {
    "resourceType": "Patient",
    "searchParams": {"name": "Smith", "birthdate": "gt2000"},
    "count": 10,
    "elements": "id,name,birthDate",
    "summary": "true"
  }
}

Parameter	Description
resourceType	Resource type (Patient, Observation, etc.)
searchParams	Search parameters as key-value pairs
count	Max results (default: 10, max: 50)
elements	Comma-separated fields to include
summary	Summary mode: true, data, text, count
total	Total count: accurate, estimate, none
tenantId	Optional tenant ID

get_fhir_resource

Retrieve a single resource by ID.

{
  "name": "get_fhir_resource",
  "arguments": {
    "resourceType": "Patient",
    "id": "123"
  }
}

patch_resource_field

Update a single field in a resource. Simple interface for common updates.

{
  "name": "patch_resource_field",
  "arguments": {
    "resourceType": "Patient",
    "resourceId": "123",
    "fieldPath": "active",
    "value": true,
    "operation": "set"
  }
}

Parameter	Description
fieldPath	FHIRPath to field (e.g., active, name[0].given)
value	New value (string, number, boolean, or JSON)
operation	set, delete, add, or remove

patch_fhir_resource

Apply multiple FHIRPath Patch operations to a resource.

{
  "name": "patch_fhir_resource",
  "arguments": {
    "resourceType": "Patient",
    "resourceId": "123",
    "operationsJson": "[{\"type\":\"replace\",\"path\":\"Patient.active\",\"value\":true}]"
  }
}

Operations format:

[
  {"type": "replace", "path": "Patient.active", "value": true},
  {"type": "add", "path": "Patient.telecom", "value": {"system": "phone", "value": "555-1234"}},
  {"type": "delete", "path": "Patient.photo"}
]

get_resource_history

Get version history for a resource.

{
  "name": "get_resource_history",
  "arguments": {
    "resourceType": "Patient",
    "id": "123",
    "count": 10
  }
}

Package Management

search_fhir_packages

Search for FHIR packages in the NPM registry with fuzzy matching.

{
  "name": "search_fhir_packages",
  "arguments": {
    "query": "us core",
    "maxResults": 10
  }
}

get_fhir_package_details

Get detailed information about a package including all versions.

{
  "name": "get_fhir_package_details",
  "arguments": {
    "packageId": "hl7.fhir.us.core"
  }
}

install_fhir_package

Install a FHIR package from the NPM registry.

{
  "name": "install_fhir_package",
  "arguments": {
    "packageId": "hl7.fhir.us.core",
    "version": "6.1.0"
  }
}

list_fhir_packages

List installed packages for a tenant.

{
  "name": "list_fhir_packages",
  "arguments": {
    "tenantId": 1
  }
}

uninstall_fhir_package

Uninstall a package from a tenant.

{
  "name": "uninstall_fhir_package",
  "arguments": {
    "packageId": "hl7.fhir.us.core",
    "version": "6.1.0"
  }
}

Job Management

start_export_job

Start a bulk export job.

{
  "name": "start_export_job",
  "arguments": {
    "resourceTypes": ["Patient", "Observation"],
    "since": "2024-01-01T00:00:00Z"
  }
}

start_import_job

Start a bulk import job.

{
  "name": "start_import_job",
  "arguments": {
    "sourceUrl": "https://storage.example.com/import/",
    "resourceTypes": ["Patient", "Observation"]
  }
}

get_job_status

Check the status of an import/export job.

{
  "name": "get_job_status",
  "arguments": {
    "jobId": "abc123",
    "jobType": "Export"
  }
}

list_jobs

List recent import/export jobs.

{
  "name": "list_jobs",
  "arguments": {
    "jobType": "Export",
    "maxResults": 10
  }
}

Tenant Management

list_tenants_info

List all available tenants with their configuration.

{
  "name": "list_tenants_info",
  "arguments": {}
}

Returns tenant IDs, names, FHIR versions, and validation settings.

Authorization

MCP tools respect the same authorization rules as the REST API. Configure MCP-enabled roles:

{
  "Authorization": {
    "McpEnabledRoles": ["Admin", "SystemAdmin", "Mcp", "Contributor"]
  }
}

Role	MCP Access	Description
Admin	Full	All operations
SystemAdmin	Full	Cross-tenant access
Mcp	Limited	Read, create, update, delete, search
Contributor	Full	All FHIR and MCP operations
Clinician	None	No MCP access by default
ReadOnly	None	No MCP access

Multi-Tenancy

MCP tools are tenant-aware. When multiple tenants exist:

1. Use list_tenants_info to discover available tenants
2. Pass tenantId parameter to tools
3. If omitted and only one tenant exists, it's auto-selected

Response Size Optimization

MCP responses are optimized for LLM context windows:

• Default count: 10 results (max 50)
• Use elements: Request only needed fields
• Use summary: Core fields only (true) or exclude narratives (data)
• Use total=none: Skip expensive count queries

Example optimized search:

{
  "resourceType": "Observation",
  "searchParams": {"patient": "123", "code": "http://loinc.org|85354-9"},
  "count": 5,
  "elements": "id,code,valueQuantity,effectiveDateTime",
  "summary": "data"
}

Connecting Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "ignixa-fhir": {
      "url": "http://localhost:5027/mcp",
      "transport": "sse"
    }
  }
}

Note: Replace localhost:5000 with your server's actual URL. The MCP server uses HTTP streaming (Streamable HTTP) for bidirectional communication with Claude.

Related Documentation

• Configuration - Enable experimental features
• Authorization - Configure MCP roles
• Bulk Operations - Export/import details