MCP server

Status

A basic MCP-over-HTTP tool dispatcher is live today (beta): a manifest at /api/mcp/manifest and a JSON invoke endpoint at /api/mcp/invoke, exposing three free read-only tools — casrai_lookup_credit_role, casrai_search_dictionary, and casrai_get_dictionary_term. No auth, CORS-open, same rate limits as the REST surface.

Try it now

bash

curl -sS https://casrai.org/api/mcp/manifest

curl -sS -X POST https://casrai.org/api/mcp/invoke \
  -H 'Content-Type: application/json' \
  -d '{"tool":"casrai_lookup_credit_role","args":{"name_or_slug":"conceptualization"}}'

Ask CASRAI over MCP — for subscribers

A fourth tool, casrai_ask, puts the full Regulatory Radar assistant inside your agent: a research-administration question in, a cited answer out, grounded in CASRAI’s published corpus plus the U.S. federal and funder regulatory sources the subscription monitors. It authenticates with a CASRAI API key — create up to five at /account/api-keys — and the key resolves to the same entitlement and the same 150-answers-a-day allowance as the website, because a key is an identity, not a separate product. Without an active subscription the tool answers with a pointer here rather than an answer.

casrai_ask (Regulatory Radar subscription required)

bash

curl -sS -X POST https://casrai.org/api/mcp/invoke \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer casrai_pk_YOUR_KEY' \
  -d '{"tool":"casrai_ask","args":{"question":"Which 2 CFR 200 procurement thresholds changed most recently?"}}'

Since 2026-09-03 there is a real Model Context Protocol endpoint at POST /api/mcp — JSON-RPC 2.0 over the Streamable HTTP transport, answering initialize, tools/list and tools/call. Point an MCP client at that URL directly; no adapter and no manifest translation is needed. Send the key as an Authorization header on the connection and the three lookup tools keep working without it.

The MCP handshake, verbatim

bash

curl -sS -X POST https://casrai.org/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}'

curl -sS -X POST https://casrai.org/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

curl -sS -X POST https://casrai.org/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer casrai_pk_YOUR_KEY' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"casrai_ask","arguments":{"question":"Which 2 CFR 200 procurement thresholds changed most recently?"}}}'

A tool that refuses — no key, no subscription, allowance spent — comes back as a successful JSON-RPC result carrying isError: true and a readable explanation, rather than a transport error, so the model can act on it. Only protocol faults (malformed JSON, an unknown method) are JSON-RPC errors. The older flat /api/mcp/invoke dispatcher and its manifest remain for existing integrations.

Connecting an MCP client

Most desktop MCP clients read a JSON config file listing the servers they should connect to. CASRAI’s endpoint is a remote HTTP server rather than a local command, so it goes in under the client’s remote-server syntax. For Claude Desktop that is claude_desktop_config.json; other clients use the same shape under a different filename. Restart the client after editing it.

claude_desktop_config.json

json

{
  "mcpServers": {
    "casrai": {
      "type": "http",
      "url": "https://casrai.org/api/mcp",
      "headers": {
        "Authorization": "Bearer casrai_pk_YOUR_KEY"
      }
    }
  }
}

Omit the headers block entirely and the three dictionary and CRediT lookup tools still work — they are free and need no key. The Authorization header is only what lets casrai_ask resolve your subscription. If your client cannot send custom headers on a remote server, use the @casrai/mcp-server npm package instead, which runs locally over stdio and reads the key from an environment variable.

What MCP is

The Model Context Protocol is an open specification, originally published by Anthropic and now implemented by multiple agent runtimes, for connecting language-model agents to external tools and data sources. An MCP server advertises a small, typed set of tools and resources; an MCP client (an agent host) discovers those tools and invokes them on the model's behalf. See the Model Context Protocol specificationfor the wire-level details and the canonical client and server SDKs.

The protocol matters here because it is the first widely-adopted convention for letting an agent ask, in a single round-trip, "give me the authoritative definition of research integrityfrom the CASRAI Dictionary" — and receive back a typed, citation-bearing result rather than a best-effort hallucination from training data.

Why a dictionary belongs behind an MCP server

Controlled vocabularies are a classic retrieval-augmented generation target. They are small enough to enumerate, large enough to exceed a useful prompt budget, and they change. An MCP tool that hands an agent the canonical definition, examples, counter-examples, aliases, and relationships for a term — in JSON, with a stable identifier — gives the agent something it can cite. That is materially better than a paragraph of paraphrase, both for the human reading the agent's output and for downstream systems that may parse it.

The same argument applies to the CRediT contributor roles. An editorial assistant that drafts an "Author contributions" paragraph for a manuscript should be reading the 14 role definitions from the canonical source, not from a training snapshot that may predate ANSI/NISO Z39.104-2022 or its 2026 revision.

The tools, as they actually are

Four tools, derived from the same manifest the server answers tools/listfrom, so this list cannot drift from what your client receives. Three are free and keyless; the fourth needs a subscription.

casrai_lookup_credit_role (free)

json

{
  "name": "casrai_lookup_credit_role",
  "description": "Look up one of the 14 CRediT contributor roles by name or slug.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name_or_slug": { "type": "string", "description": "e.g. 'conceptualization' or 'Formal analysis'." }
    },
    "required": ["name_or_slug"]
  }
}

casrai_search_dictionary (free)

json

{
  "name": "casrai_search_dictionary",
  "description": "Full-text search across CASRAI Dictionary terms. Returns slugs and titles, not full bodies.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "limit": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 }
    },
    "required": ["query"]
  }
}

casrai_get_dictionary_term (free)

json

{
  "name": "casrai_get_dictionary_term",
  "description": "Return the full record for one CASRAI Dictionary term, by slug.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "slug": { "type": "string", "description": "Term slug, e.g. 'data-management-plan-dmp'." }
    },
    "required": ["slug"]
  }
}

casrai_ask (Regulatory Radar subscription required)

json

{
  "name": "casrai_ask",
  "description": "Ask a research-administration question and get a cited answer grounded in CASRAI's corpus plus the monitored regulatory sources.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "question":  { "type": "string", "description": "Plain text, up to 400 characters." },
      "thread_id": { "type": "string", "description": "Optional, to continue a previous conversation." },
      "persona":   { "type": "string", "description": "Optional caller-supplied label; partitions caching and analytics." }
    },
    "required": ["question"]
  }
}

Authentication

The three lookup tools accept anonymous traffic, subject to the same rate limits as the GraphQL and REST surfaces. casrai_ask requires a CASRAI API key sent as Authorization: Bearer casrai_pk_…; create up to five at /account/api-keys and revoke any of them from the same page. A key is an identity, not a privilege: it resolves to the same entitlement, the same allowance, and the same guard chain your browser session would, which is why a key belonging to an account without a subscription gets the same pointer to Regulatory Radar that a signed-out browser does.

What this server does not do

Stated explicitly because an MCP client discovers capabilities at connection time and advertising one that is not served is worse than not having it. There is no SSE streaming, no session management (Mcp-Session-Id), no resources, no prompts, and no sampling — the server declines resources/list and prompts/list with a proper JSON-RPC -32601 rather than an empty list. It is a stateless tool server, and capabilities in the initialize response lists exactly tools.

Versioning

The tool surface follows the same versioning rules as the rest of the platform: additive changes ship without a version bump; breaking changes are announced on the API changelog at least one quarter before they take effect. The MCP server advertises its protocol version on the initialise handshake per the upstream MCP specification.