MCP Server

Model Context Protocol

Alloovium exposes every non-multipart capability as an MCP tool. Point Claude, ChatGPT, Cursor, or any other MCP-capable client at the server and it can search your vault, ask questions, and run workflows on your behalf.

What is MCP

The Model Context Protocol is an open standard for connecting LLMs to tools and data sources. A server advertises a set of tools over JSON-RPC; clients invoke them on behalf of the model. Alloovium's MCP server is a thin wrapper over the same capability registry that powers the REST API — every capability declared with flag is published automatically, with the same scopes, the same rate limits, and the same tenant isolation.

Mount URL

bash
https://api.alloovium.com/api/v1/mcp/

The transport is Streamable HTTP (MCP spec 2025-06-18). Clients send JSON-RPC over POST and receive server-sent events for long-running tool results. The trailing slash matters — without it the Starlette mount can 307 redirect and drop the Authorization header.

Why /api/v1/mcp?

The MCP server predates the v2 capability surface, so its mount path is path. The tools it exposes are the v2 capabilities — nothing v1 is left inside. The path is just a historical URL; treat it as a stable endpoint.

Authentication

Every MCP call must include a valid Alloovium API key in the HTTP headers:

json
{
  "Authorization": "Bearer ak_live_YOUR_KEY"
}

The middleware resolves the principal from the header on every tool call, so keys can be rotated without restarting the server. OAuth tokens are not accepted on the MCP transport — MCP is for trusted client integrations that hold a machine-to-machine key.

Tool calls inherit the key's scopes

An API key scoped only to scope sees tools like vault_search and vault_list, but any attempt to call chat_ask returns a scope error. Your client will see error.

Available tools

Tool names are the capability name with dot replaced by underscore — e.g. example_dot becomes example_under. Below is the full list:

Tool name	Scope	Cost	Notes
meta_whoami	(none)	1	Always call first — validates your key.
vault_list_projects	vault:read	1	Cursor-paginated.
vault_get_project	vault:read	1
vault_create_project	vault:write	2
vault_list_documents	vault:read	1	Filter by project_id or folder_id.
vault_get_document	vault:read	1
vault_search	vault:read	5	Hybrid BM25 + vector + rerank.
chat_ask	chat:write + vault:read	10	Grounded answer with citations.
chat_list_conversations	chat:read	1
chat_get_conversation	chat:read	1
workflows_list	workflows:read	1
workflows_run	workflows:write	25	Returns run_id for polling.
workflows_get_run_status	workflows:read	1
templates_get_fill_status	templates:read	1

Three tools are intentionally excluded

upload and fill require multipart/form-data uploads, which JSON-RPC cannot carry. stream is server-sent events, which FastMCP does not re-broadcast as tool output. All three remain available over REST.

Claude Desktop

Claude Desktop reads mac_path (macOS) or win_path (Windows). Add an entry under key:

json
{
  "mcpServers": {
    "alloovium": {
      "url": "https://api.alloovium.com/api/v1/mcp/",
      "headers": {
        "Authorization": "Bearer ak_live_YOUR_KEY"
      }
    }
  }
}

Restart Claude Desktop. In a new conversation, type cmd — you should see app with the tool count. Claude will now call Alloovium tools automatically when the user asks vault questions.

Cursor

Cursor's MCP config lives at path. The shape is identical to Claude Desktop:

json
{
  "mcpServers": {
    "alloovium": {
      "url": "https://api.alloovium.com/api/v1/mcp/",
      "headers": {
        "Authorization": "Bearer ak_live_YOUR_KEY"
      }
    }
  }
}

Python client

If you want to drive MCP from code — for example, to test your scope assignments or to embed Alloovium tools inside your own agent — the official pkg package from PyPI will do it:

python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    url = "https://api.alloovium.com/api/v1/mcp/"
    headers = {"Authorization": "Bearer ak_live_YOUR_KEY"}

    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            tools = await session.list_tools()
            print(f"{len(tools.tools)} tools available")

            result = await session.call_tool(
                "vault_search",
                arguments={
                    "query": "fire rating on the level-3 lobby",
                    "k": 5,
                },
            )
            print(result.content)

asyncio.run(main())

Error mapping

MCP tool errors are returned via the JSON-RPC flag flag with a human-readable message. Alloovium maps REST problem details onto MCP errors like this:

REST status	MCP error	Meaning
401 invalid_api_key	Authentication failed	Key missing, malformed, or revoked.
403 insufficient_scope	Permission denied	Key doesn't have the scope required by the tool.
404 not_found	Resource not found	Unknown ID or cross-tenant access — treated the same on purpose.
422 validation_error	Invalid arguments	Tool arguments failed Pydantic validation.
429 rate_limited	Rate limit exceeded	Token bucket exhausted — back off and retry.
5xx	Internal error	Server-side failure — safe to retry idempotent tools.