> Markdown export: /developers/mcp-overview.md
> HTML: /developers/mcp-overview
---
description: MCP endpoint, authentication, and the v1 tool surface for connecting AI assistants to Eigen Mesh memory.
audience: integrator
---

# MCP overview

> **In plain terms:** MCP lets AI assistants like Cursor and Claude read and write your Eigen Mesh memories over a standard connection — so your second brain follows you across tools. You do not need to understand MCP to use Eigen Mesh in the browser; see [Onboarding (managed)](/developers/onboarding-managed) for the web app path.

**Model Context Protocol (MCP)** is an open standard for connecting AI clients to external services. Eigen Mesh exposes memory operations through MCP over HTTP so your assistant can capture thoughts, search memories, and edit them without custom integration code.

## Who this is for

- **Integrators** connecting Cursor, Claude Desktop, or other MCP clients
- **Operators** verifying the `/api/mcp` endpoint is reachable after deploy

> **Browser-only users:** You can capture, search, and chat with memories in the Eigen Mesh web UI without configuring MCP. This page is for connecting external AI tools.

## Endpoint

```
https://<your-app-origin>/api/mcp
```

Replace `<your-app-origin>` with your deployment's public URL — the same value as `ORIGIN` (e.g. `https://eigen.example.com`).

The server uses **Streamable HTTP** transport (MCP spec). Clients that only support `stdio` need a local bridge; see [Connect Cursor or Claude](/developers/cursor-and-claude).

## Authentication

MCP requests require a **Bearer API key** scoped to your user account:

```
Authorization: Bearer <your-api-key>
```

Create keys in the product UI at **`/api-keys`** after sign-in, or ask your operator to provision one.

The server resolves the key to your `user_id` before any tool runs. All memory operations are tenant-isolated via Row Level Security — you never see another user's thoughts.

## Available tools (HTTP MCP)

| Tool | Purpose |
|------|---------|
| `capture_thought` | Store a new raw thought |
| `retrieve_thoughts` | Hybrid search, or browse recent thoughts (`order=created_at`) |
| `edit_thought` | Natural-language edit of an existing thought |
| `delete_thought` | Archive (soft-remove) a thought |

Full argument and response contracts: [MCP tools reference](/developers/mcp-tools).

### Not on HTTP MCP

These tools are available in the **in-app chat agent** only:

- Notes: `create_text_file`, `list_text_files`, `get_text_file`, `update_text_file`, `append_text_file`, `delete_text_file`, `search_text_files`, `link_text_file_to_thought`, `unlink_text_file_from_thought`

Legacy tools removed from HTTP MCP: `list_thoughts` (use `retrieve_thoughts` with `order=created_at`), `answer_question` (retrieve in your client, then compose).

## Security: embeddings never returned

Tool results contain **text and scores only** — never raw embedding vectors. See [Embeddings boundary](/developers/embeddings-boundary).

## Typical workflow

```mermaid
sequenceDiagram
  participant Client as MCP_Client
  participant App as Eigen Mesh
  participant DB as Postgres_pgvector

  Client->>App: capture_thought (Bearer key)
  App->>DB: persist enrich embed graph
  App-->>Client: thought id summary

  Client->>App: retrieve_thoughts query
  App->>DB: hybrid search rerank
  App-->>Client: ranked text matches

  Note over Client: Client composes answer from matches
```

## Troubleshooting

See [Troubleshooting](/developers/troubleshooting) — MCP section for 401 errors, missing tools, and connection issues.

## Next steps

- [Connect Cursor or Claude](/developers/cursor-and-claude) — client configuration
- [First memory walkthrough](/developers/first-memory-walkthrough) — end-to-end tutorial
- [MCP tools reference](/developers/mcp-tools) — full API contract