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, consume an approval for one exact execution, and preserve provider attempts and observed effects.

Start with the flow you need#

Start with approval. Create an API key and call request_approval before a governed action. If your integration only needs the approval decision, this is the basic flow.

To connect that decision to what runs afterward, use execution receipts. Add three calls: authorize the exact request, record each provider attempt, and record what changed. Your API key and MCP connection remain reusable. Only the authorization for that specific approved execution can be used once.

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 18 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.