Overview & connection

The Maetra MCP server gives Model Context Protocol clients capability-based access to Task Guard, Govern, and Secure using the same workspace API key as the REST API.

A connected agent can anchor work to a user-authorized task, check whether proposed actions remain aligned, scan content, request policy evaluation or human approval, and report what an action actually changed.

The MCP endpoint is:

At a glance#

Authentication and capability access#

Every MCP request carries a workspace API key:

Without a valid key, the server returns JSON-RPC error -32001. Workspace MCP access must also be enabled. The key's scopes, module entitlements, and workspace configuration determine which tools are available.

At the start of every new user turn or work cycle—and after context compaction, restart, or an access refresh—call:

It returns:

• the enabled secure, govern, and task_guard capabilities
• the exact tools currently allowed for each capability
• required host behaviour
• a short-lived mcp_access_token
• the token expiry

Pass that mcp_access_token to every later Maetra capability tool call. get_mcp_access is the only tool that does not require it.

Important Do not cache the capability token across work cycles. Refresh it with get_mcp_access, and never call a tool whose capability is disabled in the returned access document.

Capability-dependent tools#

tools/list is dynamic. It always includes get_mcp_access, then includes only the tools allowed for the current workspace and key. A workspace with every capability enabled can receive up to 15 tools.

See the Tools reference for inputs and required behaviour.

Connecting a client#

Claude Desktop / Code

Add the HTTP server to your MCP client config:

{
  "mcpServers": {
    "maetra": {
      "type": "http",
      "url": "https://mcp.maetra.io/mcp",
      "headers": {
        "Authorization": "Bearer maetra_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Raw JSON-RPC

curl -X POST https://mcp.maetra.io/mcp \
  -H "Authorization: Bearer $MAETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "0.1.0" }
    }
  }'


curl -X POST https://mcp.maetra.io/mcp \
  -H "Authorization: Bearer $MAETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

Supported JSON-RPC methods#

The server supports batched JSON-RPC requests. Do not batch a capability tool with the get_mcp_access call it depends on, because the later request needs the token returned by the preflight.