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

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

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.