A Model Context Protocol (MCP) server for the DERIVA platform. Exposes ERMrest and Hatrac as MCP tools with per-request OAuth authentication via Credenza.

• Transport Modes
• Installation
• Quick Start
  • stdio (local development)
  • HTTP (production)
• Configuration Reference
• Built-in Tools
• RAG Subsystem
• Safety Controls
  • Anonymous Access
• Plugin Framework
• Health Endpoint

Requires Python 3.11+. Install with uv (recommended) or pip.

# Install from the repository
uv pip install git+https://github.com/informatics-isi-edu/deriva-mcp-core.git

# With RAG support (ChromaDB and pgvector dependencies)
uv pip install "deriva-mcp-core[rag] @ git+https://github.com/informatics-isi-edu/deriva-mcp-core.git"

For development:

git clone https://github.com/informatics-isi-edu/deriva-mcp-core.git
cd deriva-mcp-core
uv sync --extra dev --extra rag

stdio mode reads credentials from ~/.deriva/credential.json -- the same file used by deriva-py CLI tools. No additional configuration is required.

Run the server:

deriva-mcp-core
# or explicitly:
deriva-mcp-core --transport stdio

Configure Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "deriva": {
      "command": "deriva-mcp-core",
      "args": [
        "--transport",
        "stdio"
      ]
    }
  }
}

By default, all mutating tools are disabled in stdio mode as well -- set DERIVA_MCP_DISABLE_MUTATING_TOOLS=false if you need write access.

HTTP mode validates each request's Bearer token against Credenza and exchanges it for a DERIVA-scoped derived token. Create a deriva-mcp.env file (see Configuration Reference) and run:

deriva-mcp-core --transport http --host 0.0.0.0 --port 8000

The server loads deriva-mcp.env from the first path found in:

1. /etc/deriva-mcp/deriva-mcp.env (system-wide)
2. ~/deriva-mcp.env (user home)
3. ./deriva-mcp.env (current directory)

Use --config /path/to/file to override.

Minimal deriva-mcp.env for HTTP:

DERIVA_MCP_CREDENZA_URL = https://your-host/authn
DERIVA_MCP_SERVER_URL = https://your-host/mcp
DERIVA_MCP_SERVER_RESOURCE = https://your-host/mcp
DERIVA_MCP_CLIENT_SECRET = your-client-secret
DERIVA_MCP_DISABLE_MUTATING_TOOLS = false

For Docker Compose deployments, see the deriva-docker repository and the Deployment Guide.

Mutating tools (* below) are disabled by default (DERIVA_MCP_DISABLE_MUTATING_TOOLS=true). Set it to false to enable them.

The RAG subsystem provides semantic search over DERIVA documentation and catalog schemas. It is disabled by default and requires the rag optional dependency group.

Enable it:

DERIVA_MCP_RAG_ENABLED = true

On startup (when DERIVA_MCP_RAG_AUTO_UPDATE=true), the server incrementally crawls the built-in documentation sources (deriva-py, ermrest, chaise) and indexes any changed files. Catalog schemas are indexed automatically when a tool first accesses a catalog (via the on_catalog_connect lifecycle hook).

ChromaDB (default) -- embedded, zero additional services:

DERIVA_MCP_RAG_VECTOR_BACKEND = chroma
DERIVA_MCP_RAG_CHROMA_DIR = ~/.deriva-mcp/chroma

For multi-instance deployments, point all instances at a shared ChromaDB server:

DERIVA_MCP_RAG_CHROMA_URL = http://chroma:8000

pgvector -- recommended for production multi-instance deployments:

DERIVA_MCP_RAG_VECTOR_BACKEND = pgvector
DERIVA_MCP_RAG_PG_DSN = postgresql://user:pass@db:5432/deriva_mcp

Requires the pgvector PostgreSQL extension. The server creates the required table and index automatically on first startup.

All tools that write to the DERIVA catalog are registered with mutates=True. When DERIVA_MCP_DISABLE_MUTATING_TOOLS=true (the default), these tools return an error immediately without executing. The server logs a warning on startup when mutations are disabled and an info message when they are enabled, so the active state is always visible in the logs.

RAG tools write to the local vector store, not the DERIVA catalog, and are not affected by this setting.

By default all installed plugins (packages that declare the deriva_mcp.plugins entry point) are loaded. To restrict loading to a known set:

# Load only the deriva-ml plugin
DERIVA_MCP_PLUGIN_ALLOWLIST = deriva-ml

# Disable all external plugins
DERIVA_MCP_PLUGIN_ALLOWLIST =

Blocked plugins are logged at WARNING level so operators can audit what was skipped.

Set DERIVA_MCP_ALLOW_ANONYMOUS=true to allow requests without an Authorization header. This is useful for deployments serving publicly readable catalogs where requiring users to authenticate would be unnecessary friction.

Behavior:

• No token provided: the request proceeds with empty DERIVA credentials, equivalent to what an unauthenticated browser request would receive. Mutations are blocked regardless of the kill-switch setting -- anonymous access is always read-only.
• Valid token provided: normal Credenza validation and token exchange; the request runs as that authenticated user with their normal permissions.
• Invalid/expired token provided: 401 response. A client that sends a token must send a valid one -- bad tokens are never silently downgraded to anonymous.

Sub-modes:

Example (anonymous-only, public read-only catalog):

DERIVA_MCP_ALLOW_ANONYMOUS = true
# No DERIVA_MCP_CREDENZA_URL, SERVER_URL, CLIENT_SECRET etc. needed

Example (mixed mode -- auth optional):

DERIVA_MCP_ALLOW_ANONYMOUS = true
DERIVA_MCP_CREDENZA_URL = https://your-host/authn
DERIVA_MCP_SERVER_URL = https://your-host/mcp
DERIVA_MCP_SERVER_RESOURCE = https://your-host/mcp
DERIVA_MCP_CLIENT_ID = deriva-mcp
DERIVA_MCP_CLIENT_SECRET = your-client-secret

When the mutation kill switch is off, all authenticated users can execute mutating tools. To restrict mutations to users with a specific claim in their token introspection payload:

# Require membership in a specific group
DERIVA_MCP_MUTATION_REQUIRED_CLAIM = {"groups": ["deriva-mcp-mutator"]}

# Require a boolean claim
DERIVA_MCP_MUTATION_REQUIRED_CLAIM = {"mcp_can_mutate": true}

List values use OR semantics (any match is sufficient). Multiple keys use AND semantics (all must match). Users who fail the check receive an error response and a mutation_claim_denied audit event. The kill switch takes precedence when both controls are active.

External packages can register additional MCP tools, resources, and prompts by declaring a register entry point in the deriva_mcp.plugins group:

# pyproject.toml of the plugin package
[project.entry-points."deriva_mcp.plugins"]
my-plugin = "my_package.mcp_plugin:register"

The register function receives a PluginContext that exposes the same API used by the built-in tool modules:

from deriva_mcp_core import get_catalog, get_hatrac_store
from deriva_mcp_core.context import deriva_call


def register(ctx):
    @ctx.tool(mutates=False)
    async def my_read_tool(hostname: str, catalog_id: str) -> str:
        with deriva_call():
            catalog = get_catalog(hostname, catalog_id)
            # ... ERMrest calls here
        return result

    @ctx.tool(mutates=True)
    async def my_write_tool(hostname: str, catalog_id: str, data: dict) -> str:
        with deriva_call():
            catalog = get_catalog(hostname, catalog_id)
            # ... mutating calls here
        return result

Key rules:

• Every ctx.tool() call requires an explicit mutates=True or mutates=False (omitting raises TypeError at startup).
• Wrap all ERMrest/Hatrac calls in with deriva_call(): for transparent 401 handling.
• Mutating tools (mutates=True) emit audit_event on success and failure.
• Use ctx.submit_task(coroutine, name) for long-running operations; returns a task_id immediately.

See docs/plugin-authoring-guide.md for the full guide covering credential access patterns, lifecycle hooks, RAG extension, and testing.

• Usage Guide -- natural language prompt examples for all tool categories
• Plugin Authoring Guide -- writing and testing external plugins
• Deployment Guide -- Docker Compose, VM, reverse proxy, vector store backends

The HTTP server exposes a health endpoint at GET /health that returns {"status": "ok"} with no authentication required. Suitable for Docker health probes and load balancer checks.

curl http://localhost:8000/health
# {"status":"ok"}

deriva-mcp-core is alpha-quality software. The API and configuration surface are still evolving and breaking changes may occur between releases without advance notice. It has been validated end-to-end against live DERIVA deployments, but has not yet seen broad production use. Use in production environments is at your own risk. Bug reports and contributions are welcome via the issue tracker.