MCP server

Connect a client

The server is one URL: POST https://casrai.org/api/mcp, JSON-RPC 2.0 over the Streamable HTTP transport. Send your key as an Authorization header on the connection. Leave it off and the three lookup tools still work.

Claude Code

bash

claude mcp add --transport http casrai https://casrai.org/api/mcp --header "Authorization: Bearer casrai_pk_YOUR_KEY"

# Free tools only, no key
claude mcp add --transport http casrai https://casrai.org/api/mcp

.mcp.json (Claude Code) · .cursor/mcp.json (Cursor)

json

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

Claude Code reads .mcp.json at the project root; Cursor uses .cursor/mcp.json with url and headers keys. File locations and keys can change between client versions, so check your client’s documentation if the server does not appear. Drop the headers block for the free tools.

Claude Desktop and claude.ai add remote servers as custom connectors rather than through that file. We have only documented the header setup above, so use Claude Code or Cursor for casrai_ask; see Anthropic’s current documentation for the connector flow.

Codex CLI · config.toml

toml

[mcp_servers.casrai]
url = "https://casrai.org/api/mcp"
bearer_token_env_var = "CASRAI_API_KEY"

This setting names an environment variable holding your key, which Codex sends as the Authorization bearer header; check the Codex documentation for your version. Omit bearer_token_env_var for the free tools.

What comes back

casrai_ask takes a plain-text question and returns a cited answer. Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI. Each answer cites the sources behind it, and says so when those sources do not cover a question instead of guessing. Subscribers get 150 answers a day across the website, the API and this server — a key is an identity, not a separate allowance.

A refusal — no key, no active subscription, allowance spent — comes back as a normal result carrying isError: true and a readable reason, so the model can act on it. Protocol faults and server errors are JSON-RPC errors; tool failures come back as results with isError set.

The tools

Tool names and parameters are rendered at build time from the same module the server answers tools/list from, so they cannot drift from what your client receives. The descriptions below are written for this page; your client’s copy may be worded differently.

casrai_lookup_credit_roleFree · no key

Look up a CRediT role by name or slug. Returns the canonical definition, group, and metadata.

name_or_slug · string, required — Role name (e.g., 'Conceptualization') or slug (e.g., 'conceptualization').

casrai_search_dictionaryFree · no key

Search the CASRAI Dictionary of research-administration terms. Returns matching entries.

query · string, required — Free-text query, matched case-insensitively against slug and title.
domain · string — Optional domain slug filter (e.g. "persistent-identifiers").
limit · integer — Maximum number of results to return.

casrai_get_dictionary_termFree · no key

Get the full definition of a dictionary term by slug.

slug · string, required — Term slug, lowercase kebab-case (e.g. "research-integrity").

casrai_search_nikolaiFree · no key

Search NIKOLAI (Nomenclature & Index for Knowledge Ontologies, Lexicons & AI Interoperability), CASRAI’s frontier-AI-safety Dictionary of Elements. Returns matching elements with their track and a short excerpt. Every crosswalk row NIKOLAI publishes is CASRAI’s own shadow-mapping reading unless the row’s declared_by field is non-null, which only happens through a CASRAI-editor-reviewed Mapping Declaration — see casrai_get_nikolai_element for the full picture on any one element.

query · string, required — Free-text query, matched case-insensitively against slug and title.
track · string — Optional NIKOLAI-track slug filter (e.g. "n4-claims-argument").
limit · integer — Maximum number of results to return.

casrai_get_nikolai_elementFree · no key

Get the full definition of a NIKOLAI element by slug, including its complete crosswalk (each row flagged is_shadow true unless a CASRAI-editor-approved Mapping Declaration made it false) and any published Mapping Declarations for it.

slug · string, required — NIKOLAI-element slug, lowercase kebab-case (e.g. "safety-case").

casrai_askSubscription + key

Ask CASRAI a research-administration question and get a cited answer. Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI. Requires a CASRAI API key (Authorization: Bearer casrai_pk_…) from an account with an active Regulatory Radar subscription; create keys at https://casrai.org/account/api-keys. Subscribers get 150 answers a day; every answer cites the sources behind it.

question · string, required — The question, plain text, up to 400 characters.
thread_id · string — Optional thread id from a previous casrai_ask result, to continue that conversation.
persona · string — Optional caller-supplied label (lowercase slug, max 32 chars) identifying the asking context. Used to group cached answers and usage figures; it does not change the sources searched or the answer’s scope.

Raw JSON-RPC

tools/list and tools/call

bash

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

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

Keys, limits, scope

Up to 5 active keys per account at /account/api-keys; revoke any of them from the same page. A key resolves to the same entitlement and the same allowance as your browser session.
The lookup tools need no key.
Stateless tool server: no SSE streaming, no Mcp-Session-Id, no resources, no prompts, no sampling. capabilities on initialize lists exactly tools, and resources/list is declined with JSON-RPC -32601 rather than an empty list.
The API changelog sets the versioning and deprecation policy for the GraphQL and REST endpoints. It does not yet cover this server.

Legacy dispatcher

Before the protocol endpoint above, the same tools were served by a flat HTTP dispatcher: a manifest at /api/mcp/manifest and a JSON invoke route at /api/mcp/invoke. Both remain for the integrations that already use them. New clients should use POST /api/mcp.

Legacy manifest and invoke

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"}}'