API & MCP

MCP server

eli.ai doesn't just consume MCP servers (Tools, MCP & HITL) — it is one. Any MCP client — Claude, an IDE agent, another platform — connects to your workspace over streamable HTTP and gets the knowledge graph and the governed data layer as native tools, under the same RLS scoping and provenance as everything else.

Endpoint & auth

The server lives at POST /api/mcp (streamable-HTTP transport). Authentication is the same workspace or user API key as /api/v1:

every MCP requestbash

Authorization: Bearer eli_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The transport resolves exactly one workspace before constructing the server; every tool call executes under that workspace's row-level security. User keys with more than one possible workspace send X-Workspace-Id. There is no workspace field in a model-supplied tool input. See Authentication for creating keys and scopes.

Stateless streamable HTTP

The server is stateless: each JSON-RPC request is self-contained, initialized per call, and served by whichever web process receives it — no session affinity, no SSE subscription required, safe behind any load balancer. Clients that prefer long-lived SSE streams still work, but nothing depends on them.

Tool catalog

`kb_search`	tool	Hybrid lexical + semantic search over the workspace KB; returns scored chunks with doc metadata.
`kb_entity_lookup`	tool	Resolve entities by name (exact / alias / fuzzy); returns entity cards with type, aliases, mention counts, top relations.
`kb_entity_get`	tool	Fetch one entity by id with its full card and governance metadata.
`kb_document_lineage`	tool	Return a document's origin, revisions, governance, derived graph state, audit trail, and downstream dependencies.
`kb_graph_query`	tool	Expand the knowledge graph around seed entities (structured params: seeds, depth 1–3, type filters); returns nodes, typed edges, truncated flag.
`kb_data_discover`	tool	List the live-data surface: enabled entity bindings and domain components in scope, with labels, descriptions, and param specs.
`kb_data_lookup`	tool	Execute a domain component or binding with validated params; returns columns, rows (maxRows-capped, truncated flag), duration, and the dataCallId provenance anchor.
`eli_query`	tool	The full pipeline in one call — retrieval + entity resolution + governed lookups → structured answer with [Sn]/[Dn] citations (same shape as POST /api/v1/query).

All eight tools are read-only. The fine-grained tools suit agents that orchestrate their own reasoning; eli_query suits clients that want eli.ai to do the whole job and hand back a cited result. Every kb_data_lookup and eli_query data access writes the same append-only data_calls provenance row as any internal call, attributed to the API key.

Resource catalog

`eli://workspace/summary`	resource	ACL-filtered workspace counts and recent visible documents.
`eli://workspace/manifest`	resource	The governed knowledge manifest for the selected workspace.

Connect from Claude

Claude Code:

claude mcp addbash

claude mcp add --transport http eli https://your-host/api/mcp \
  --header "Authorization: Bearer eli_sk_..."

Or in an MCP client config file (Claude Desktop, IDEs, and most other clients accept this shape):

.mcp.jsonjson

{
  "mcpServers": {
    "eli": {
      "type": "http",
      "url": "https://your-host/api/mcp",
      "headers": {
        "Authorization": "Bearer eli_sk_..."
      }
    }
  }
}

Once connected, ask naturally: "Using the eli tools, what do we know about Acme Corp — and what is their current churn risk?" The client will chain kb_entity_lookup → kb_data_discover → kb_data_lookup, or just call eli_query.

Guarantees

Workspace isolation— the key picks the workspace; FORCE-RLS makes other tenants' rows nonexistent, not forbidden.
Source ACL enforcement — connector principals are mapped to the caller and enforced before document chunks or document-derived graph context reach a tool result.
Read-only surface — no tool exposed over MCP writes to the KB or to external systems; data-layer access is single-statement SELECT/WITH through governed components.
Provenance & attribution — external data access is recorded per call with the exact SQL, params, timing, and status; keyed usage is attributed to its API key exactly like /api/v1 traffic, and the same rate-limit posture applies (Errors & rate limits).
Secrets stay home — connector credentials never appear in tool results; clients see component slugs and descriptions, never connection configs.

Plain HTTP instead?

If your integration isn't an MCP client, the same pipeline is available as ordinary JSON over POST /api/v1/query.