# 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:

```
https://mcp.maetra.io/mcp
```

### At a glance

|                     |                                               |
| ------------------- | --------------------------------------------- |
| **Server name**     | `maetra-mcp`                                  |
| **Version**         | `1.0.0`                                       |
| **MCP protocol**    | `2024-11-05`                                  |
| **Transport**       | HTTP, JSON-RPC 2.0 over `POST`                |
| **Endpoint**        | `POST https://mcp.maetra.io/mcp`              |
| **Auth**            | `Authorization: Bearer maetra_...` (required) |
| **Streaming (SSE)** | Not enabled — request/response only           |
| **Health**          | `GET /health`                                 |

### Authentication and capability access

Every MCP request carries a workspace API key:

```
Authorization: Bearer maetra_xxxxxxxxxxxxxxxxxxxx
```

Without a valid key, the server returns JSON-RPC error `-32001`. Workspace MCP access must also be enabled. The key's [scopes](https://maetra.io/docs/getting-started/authentication), 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:

```
get_mcp_access
```

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.

| Capability | Tools |
| ---------- | ----- |
| Access | `get_mcp_access` |
| Task Guard | `start_task`, `get_task_context`, `check_task_alignment`, `explain_task_relationship`, `record_task_progress`, `record_action_effect`, `complete_task` |
| Secure | `check_action`, `list_active_rules`, `create_rule`, `update_rule` |
| Govern | `request_approval`, `get_approval_status`, `list_active_policies`, `authorize_execution`, `record_execution_attempt`, `record_execution_effect` |

See the [Tools reference](https://maetra.io/docs/mcp-server/tools-reference) for inputs and required behaviour.

### Connecting a client

#### Claude Desktop / Code

Add the HTTP server to your MCP client config:

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

#### Raw JSON-RPC

```bash
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

| Method            | Behaviour |
| ----------------- | --------- |
| `initialize`      | Returns server capabilities and instructions for the enabled Maetra controls. |
| `tools/list`      | Returns `get_mcp_access` and the capability tools currently permitted. |
| `tools/call`      | Invokes a named tool with an `arguments` object. |
| `ping`            | Keep-alive; returns `{}`. |
| `notifications/*` | Accepted and acknowledged without a response body. |

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.