# MCP server

Datalumo runs a remote [MCP](https://modelcontextprotocol.io) server, so AI assistants such as Grok, Claude Code and Cursor can search your knowledge bases and push content to them. It offers the same actions as the HTTP API, with the same API keys.

```
https://datalumo.app/mcp
```

The server uses the Streamable HTTP transport. On a self-hosted install, use your own address, such as `https://datalumo.example.com/mcp`.

The server signs in with an API key sent as a header. Clients that only sign in with OAuth, such as ChatGPT, can't connect yet. On Claude.ai, add it as a custom connector with a request header where your plan offers that.

## Connect

1. On the **API keys** page, create a key. Give it only the permissions the assistant needs: `search` and `chat` to look things up, `pages.write` to add content. See [Authentication](/docs/authentication).
2. Add the server to your assistant with the URL above and the header `Authorization: Bearer YOUR_API_KEY`.

### Grok

In the xAI API, add the server as a tool:

```json
{
  "type": "mcp",
  "server_url": "https://datalumo.app/mcp",
  "server_label": "datalumo",
  "headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
```

In the Grok CLI:

```bash
grok mcp add --transport http datalumo https://datalumo.app/mcp \
  --header "Authorization: Bearer $DATALUMO_TOKEN"
```

### Other clients

Most clients take a URL and headers. For example, in `.mcp.json`:

```json
{
  "mcpServers": {
    "datalumo": {
      "type": "http",
      "url": "https://datalumo.app/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

## Tools

| Tool | Does | Permission |
|---|---|---|
| `get_account` | Your organisation, and the sources and widgets the key can use | any |
| `search` | Search through a search widget | `search` |
| `chat` | Ask a chat widget a question; pass `conversation_id` for a follow-up | `chat` |
| `summarize` | Short answer from a search widget's sources | `summarize` |
| `list_pages` | List the pages in a source | `pages.read` |
| `push_page` | Add or update one page | `pages.write` |
| `push_pages` | Add or update up to 50 pages | `pages.write` |
| `delete_page` | Delete a page | `pages.write` |
| `index_source` | Start indexing and report progress | `pages.write` |

Each tool returns the same JSON as the matching API endpoint. `chat` waits for the whole answer, which can take up to a minute with slower models. `chat` and `summarize` use answers from your plan, like the API does. When a call fails, the tool returns the API's status and message, for example `HTTP 403: Token is missing the pages.write ability.`
