> For the complete documentation index, see [llms.txt](https://docs.maetra.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maetra.io/mcp-server/overview-and-connection.md).

# Overview & connection

The **Maetra MCP server** gives AI agents and assistants that speak the [Model Context Protocol](https://modelcontextprotocol.io) access to Govern and Secure as **tools** — authenticated with the same workspace API key you use for the REST API.

Give an agent this server and it can check its own actions, request human approval, and manage rules — in-line, using tools it already knows how to call.

The MCP server is available at:

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

Every request carries your workspace API key as a bearer token — the same key used for the REST API (see [Authentication](/getting-started/authentication.md)):

```
Authorization: Bearer maetra_xxxxxxxxxxxxxxxxxxxx
```

Without it, the server returns JSON-RPC error `-32001`. The key's [scopes](/getting-started/authentication.md) still apply — e.g. `update_rule` needs `secure:rules:write`.

### Tools

Seven tools, backed by the REST API.

| Tool                                                     | Backs             | Purpose                                   |
| -------------------------------------------------------- | ----------------- | ----------------------------------------- |
| [`check_action`](/mcp-server/tools-reference.md)         | Secure scan       | Scan a prompt, tool call, or output.      |
| [`list_active_rules`](/mcp-server/tools-reference.md)    | Secure rules      | List active Secure rules.                 |
| [`create_rule`](/mcp-server/tools-reference.md)          | Secure rules      | Create a Secure rule.                     |
| [`update_rule`](/mcp-server/tools-reference.md)          | Secure rules      | Update an existing Secure rule.           |
| [`request_approval`](/mcp-server/tools-reference.md)     | Govern checkpoint | Request human approval for an action.     |
| [`get_approval_status`](/mcp-server/tools-reference.md)  | Govern checkpoint | Poll a checkpoint (long-polls up to 20s). |
| [`list_active_policies`](/mcp-server/tools-reference.md) | Govern policies   | List active Govern policies.              |

### Connecting a client

{% tabs %}
{% tab title="Claude Desktop / Code" %}
Add to your MCP client config (e.g. `claude_desktop_config.json`):

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

{% endtab %}

{% tab title="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" }'
```

{% endtab %}
{% endtabs %}

### Supported JSON-RPC methods

| Method            | Behaviour                                        |
| ----------------- | ------------------------------------------------ |
| `initialize`      | Handshake; returns server info and capabilities. |
| `tools/list`      | Returns the seven tools and their input schemas. |
| `tools/call`      | Invokes a named tool with `arguments`.           |
| `ping`            | Keep-alive; returns `{}`.                        |
| `notifications/*` | Accepted and acknowledged (no response body).    |

The server also supports **batched** requests — send an array of JSON-RPC messages and receive an array of responses. See the [end-to-end example](/mcp-server/end-to-end-example.md).