MCP Integration

MCP Integration

The idea in one paragraph

Model Context Protocol is how AI assistants call tools. IGL serves its governed identity operations as MCP tools, so an assistant in Claude, Cursor or any MCP client can ask who it is acting for, what that person is responsible for and what is due, and gets back exactly the projection an application would get: same purpose, same four gates, same signed receipt. The assistant never sees more than the purpose allows, and what it does with the answer is recorded.

Two servers, one behavior

	Hosted platform	Your own machine
Endpoint	POST https://api.id-me.ai/v1/mcp (production) or POST https://sandbox.id-me.ai/v1/mcp	POST http://127.0.0.1:8787/mcp after npm run provision
Authentication	Authorization: Bearer <key or token> and X-IGL-Tenant-Id	the caller key registered in provision/identities.mjs
Transport	JSON-RPC 2.0 over HTTP, one response per request	same
Tools	whoami, list_purposes, get_identity_context, explain_projection, list_obligations, search_graph, record_interaction	check_health, list_graphs, get_graph, search, fetch, identity_graph_whoami, provision_identity

Every hosted tool maps one to one onto a contract operation and runs through the same handler, so an assistant and an application calling REST get identical results. Each tool call is checked against the scopes of the operation it maps to; a read-only token that calls record_interaction gets a result with isError: true naming the missing scope.

The seven hosted tools

Tool	What the assistant asks	REST equivalent
whoami	Who am I acting for, under this purpose?	GET /identities/me?purpose=
list_purposes	Which purposes may I use, and what does each permit?	GET /purposes
get_identity_context	Show me this identity under this purpose	GET /identities/{id}/projection
explain_projection	Why was each node admitted or withheld?	GET /identities/{id}/projection/explain
list_obligations	What does this identity owe, to whom, by when?	GET /identities/{id}/obligations
search_graph	Find identities by name, or governed paths between two	GET /identities?q=, POST /graph/paths
record_interaction	Here is what I did with the context you gave me	POST /audit/interactions

list_obligations and search_graph take limit and cursor, and return page.nextCursor, so an assistant pages the same way an application does. record_interaction is the one every assistant should call at the end of a task: it is how "the model proceeded on truncated context" becomes a fact in the audit chain instead of a guess.

Connecting Claude Desktop or Cursor

Both read a JSON configuration. The hosted endpoint is a remote HTTP server that needs two headers, which the mcp-remote bridge supplies. The header values come from the environment block with no space after the colon, because some clients split arguments on spaces, and http-only tells the bridge that the server answers each request directly rather than over an event stream:

{
  "mcpServers": {
    "igl": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://sandbox.id-me.ai/v1/mcp",
        "--transport", "http-only",
        "--header", "Authorization:${IGL_AUTH}",
        "--header", "X-IGL-Tenant-Id:${IGL_TENANT}"
      ],
      "env": { "IGL_AUTH": "Bearer igl_test_...", "IGL_TENANT": "..." }
    }
  }
}

For Claude Desktop the file is claude_desktop_config.json (Settings, Developer, Edit Config). For Cursor it is .cursor/mcp.json in the project or ~/.cursor/mcp.json. Use a sandbox key from Quickstart: the API first; switch the URL to https://api.id-me.ai/v1/mcp with an igl_live_ key when you are ready. Put the key in the environment, not in a file you will commit.

Then ask the assistant: "Who am I acting for, and what is due this month?" It will call whoami, then list_obligations under regulatory-filing if your key's identity has consent for it, and it will tell you when something was withheld because of purpose or consent rather than inventing an answer.

The protocol, if you are writing your own client

curl -s -X POST https://sandbox.id-me.ai/v1/mcp \
  -H "authorization: Bearer $IGL_KEY" -H "x-igl-tenant-id: $IGL_TENANT" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

initialize returns the protocol version (2025-03-26), server info and the contract version. tools/list returns the seven tools with their input schemas. tools/call runs one; a governed refusal (a purpose that does not permit obligations, or a scope the credential does not have) comes back as a normal result with isError: true and the reason in content, which is what MCP clients expect, while credential and tenant failures are HTTP 401 and 403 as on REST. Notifications (messages without an id) are accepted with 202.

The local server and IGL Studio

npm run provision starts the provisioning service on your machine with the MCP endpoint at POST /mcp. A caller is recognized on first contact: the service seeds the caller's own identity graph from the registered profile, and on every later contact it replays the hash chained journal, so the caller's grants and refusals govern every tool call in the session. provision_identity turns a plain description into a graph; identity_graph_whoami answers for the caller; search and fetch are the standard retrieval pair. IGL Studio at http://127.0.0.1:8787/ is the same service with a page in front of it.

Why assistants behave better on IGL

An assistant that reaches identity data through IGL cannot overreach, because the purpose it declares bounds what it receives. It cannot pretend, because a withheld node is counted and explained. It cannot forget what it did, because record_interaction is part of the contract. And when it answers a question with the intelligence operations, it must cite the records it used, or the service refuses the answer with a 422 instead of returning it. See Policies, Agents and Workflows.