> ## Documentation Index
> Fetch the complete documentation index at: https://manager.harmix.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP reference

> POST /v1/mcp/memory endpoint, JSON-RPC methods, authentication, and protocol behavior.

Send all Memory MCP traffic to a single endpoint. Auth identifies the caller — the path is the same for every account.

## Endpoint

```
POST https://api.pam.harmix.ai/v1/mcp/memory
```

| Method | Path             | Purpose                                    |
| ------ | ---------------- | ------------------------------------------ |
| `GET`  | `/v1/mcp/memory` | SSE keep-alive for Streamable HTTP clients |
| `POST` | `/v1/mcp/memory` | JSON-RPC 2.0 MCP requests                  |

## Authentication

Memory MCP accepts **either** static agent keys or OAuth Bearer tokens.

### Desktop / script clients

```
Authorization: pam_mkey_<key>
```

Some clients prepend `Bearer `. The server accepts both forms for static keys.

Generate keys on **[Setup](https://pam.harmix.ai/setup)** — not via this endpoint.

### Browser LLM clients (Claude web, ChatGPT)

```
Authorization: Bearer <opaque_oauth_access_token>
```

Browser clients obtain tokens through OAuth 2.1 Authorization Code + PKCE:

| Step                          | Endpoint                                                       |
| ----------------------------- | -------------------------------------------------------------- |
| Discover protected resource   | `GET /.well-known/oauth-protected-resource`                    |
| Discover authorization server | `GET /.well-known/oauth-authorization-server`                  |
| Register client (DCR)         | `POST /v1/oauth/register`                                      |
| Authorize user                | `GET /v1/oauth/authorize`                                      |
| Exchange code / refresh       | `POST /v1/oauth/token` (`authorization_code`, `refresh_token`) |
| Revoke token                  | `POST /v1/oauth/revoke`                                        |

Required scope: `memory:read`. Access tokens are opaque and short-lived (about 1 hour). Refresh tokens are opaque, rotate on each refresh, and last about 30 days. Reusing a spent refresh token revokes the whole connection family.

Alternative discovery for some MCP clients: `GET /.well-known/oauth-protected-resource/v1/mcp/memory`.

See [Client setup](/docs/client-setup) for ChatGPT and Claude web connector steps.

## JSON-RPC methods

| Method                                   | Counted toward quotas? | Purpose                                             |
| ---------------------------------------- | ---------------------- | --------------------------------------------------- |
| `initialize`                             | No                     | MCP handshake; returns server info and instructions |
| `initialized`                            | No                     | Client acknowledgment (empty 200)                   |
| `tools/list`                             | No                     | Returns `retrieve_memory` tool schema               |
| `resources/list`                         | No                     | Empty list in v1                                    |
| `prompts/list`                           | No                     | Empty list in v1                                    |
| **`tools/call`** + **`retrieve_memory`** | **Yes**                | Company memory retrieval                            |

## tools/list response

The server exposes one tool in v1:

```json theme={null}
{
  "name": "retrieve_memory",
  "title": "Retrieve company memory",
  "description": "Retrieve relevant company memory for the current user's prompt. Use when the task may depend on company-specific context: people, projects, decisions, processes, priorities, history, customers, or internal terminology. Prefer calling this before making assumptions.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "prompt": { "type": "string" },
      "session_id": { "type": "string" }
    },
    "required": ["prompt"]
  },
  "annotations": {
    "title": "Retrieve company memory",
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  }
}
```

See [retrieve\_memory](/docs/retrieve-memory) for full parameter and response documentation.

## Tool result shape

Successful and error responses use HTTP 200 with this structure:

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "# Retrieved Company Context\n\n**Query:** Who are our main enterprise clients and which accounts have the highest recurring revenue?\n\n**Summary:** Enterprise clients span media and publishing; tracked MRR is concentrated in three active accounts.\n\n## Relevant Facts\n\n- [97%] **Tier-1 strategic accounts include a major broadcaster and two enterprise publishers.**\n- [95%] **Three active accounts generate documented monthly recurring revenue.**\n\n---\n*Retrieved 12 items | Avg relevance: 89% | Coverage: comprehensive*"
    }
  ],
  "structuredContent": {
    "status": "ok",
    "memory_ready": true,
    "readiness_state": "ready_rich",
    "content_text": "# Retrieved Company Context\n\n...",
    "triage": {
      "decision": "retrieve",
      "reasoning": "The query depends on company-specific client context."
    },
    "retrieval": {
      "context_summary": "Enterprise clients span media and publishing; tracked MRR is concentrated in three active accounts.",
      "total_items": 12,
      "avg_relevance_score": 0.89,
      "coverage_assessment": "comprehensive"
    },
    "diagnostics": {
      "request_id": "f30ee45b-06eb-4c46-9fa7-e76d29ba7131",
      "duration_ms": 48210,
      "estimated_tokens": 8400
    }
  },
  "isError": false
}
```

Tool-level errors set `isError: true` and include `structuredContent.error_code`:

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "Rate limit exceeded. Please try again later."
    }
  ],
  "structuredContent": {
    "status": "error",
    "error_code": "quota_exceeded",
    "error_message": "Rate limit exceeded. Please try again later."
  },
  "isError": true
}
```

## Example: tools/call

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "retrieve_memory",
    "arguments": {
      "prompt": "Who are our main enterprise clients and which accounts have the highest recurring revenue?",
      "session_id": "cursor-thread-k7m2p"
    }
  }
}
```

## Session ID and MCP headers

The server may return an `Mcp-Session-Id` response header during MCP handshake. `session_id` in tool arguments is **optional** — if omitted, the server uses that MCP session ID for the call.

An explicit `session_id` overrides the handshake ID (for example, one ID per agent thread). The server stores your last **5 prompts** per session in Redis (30-day TTL) and may include the last **3** prior prompts in the **triage** step on the next call when triage is enabled. This is a lightweight server-side hint — not full conversational context.

## Related

* [retrieve\_memory](/docs/retrieve-memory) — tool parameters and response fields
* [Quotas and limits](/docs/quotas-and-limits) — what counts toward limits
* [Error codes](/docs/error-codes) — all `error_code` values
* [Developer API](/docs/developer-api-overview) — key management and request history