# MCP server

> Connect Claude, ChatGPT, Cursor, VS Code and other AI assistants to LifeButler with the Model Context Protocol.

LifeButler speaks the [Model Context Protocol](https://modelcontextprotocol.io), so AI assistants can work with your workspaces directly: *"What's on for the kids this week?"*, *"Put everything for lasagne on the shopping list"*, *"Find the Stadtwerke bill from March and tell me the amount"*.

| | |
|---|---|
| URL | `https://api.lifebutler.io/mcp` |
| Transport | Streamable HTTP (stateless, JSON responses) |
| Auth | `Authorization: Bearer lb_live_…` – an [API key](/developers/authentication) |

The MCP server uses the same keys, scopes and checks as the REST API: the assistant can do exactly what the key allows, in the workspaces of the key – nothing more. Create a separate key for each assistant, with only the scopes it needs. Read-only scopes are a good start.

## Claude Code

```bash
claude mcp add --transport http lifebutler https://api.lifebutler.io/mcp \
  --header "Authorization: Bearer lb_live_…"
```

## Claude Desktop

Claude Desktop connects to remote servers with an `Authorization` header through `mcp-remote` (needs Node.js). In *Settings → Developer → Edit config*:

```json
{
  "mcpServers": {
    "lifebutler": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.lifebutler.io/mcp", "--header", "Authorization:${LIFEBUTLER_AUTH}"],
      "env": { "LIFEBUTLER_AUTH": "Bearer lb_live_…" }
    }
  }
}
```

## Cursor

`~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "lifebutler": {
      "url": "https://api.lifebutler.io/mcp",
      "headers": { "Authorization": "Bearer lb_live_…" }
    }
  }
}
```

## VS Code (GitHub Copilot)

`.vscode/mcp.json`:

```json
{
  "inputs": [{ "type": "promptString", "id": "lifebutler-key", "description": "LifeButler API key", "password": true }],
  "servers": {
    "lifebutler": {
      "type": "http",
      "url": "https://api.lifebutler.io/mcp",
      "headers": { "Authorization": "Bearer ${input:lifebutler-key}" }
    }
  }
}
```

## OpenAI Codex CLI

`~/.codex/config.toml`:

```toml
[mcp_servers.lifebutler]
url = "https://api.lifebutler.io/mcp"
bearer_token_env_var = "LIFEBUTLER_KEY"
```

## Other clients

Any MCP client that supports Streamable HTTP with a custom header works. Connectors in the web versions of Claude and ChatGPT sign in with OAuth instead of a key; that is planned for a later version.

## Tools

Each tool is one [API operation](/developers/reference) and takes the same fields (path, query and body together). Read-only tools are marked as such, so clients can run them without asking; deleting tools are marked destructive.

| Tool | What it does | Scope |
|---|---|---|
| `get_me` | Who am I *(read-only)* | `workspaces:read` |
| `list_workspaces` | List workspaces *(read-only)* | `workspaces:read` |
| `get_workspace` | Get a workspace *(read-only)* | `workspaces:read` |
| `list_members` | List members *(read-only)* | `workspaces:read` |
| `list_events` | List appointments in a time range *(read-only)* | `calendar:read` |
| `get_event` | Get an appointment *(read-only)* | `calendar:read` |
| `create_event` | Create an appointment | `calendar:write` |
| `update_event` | Change an appointment | `calendar:write` |
| `delete_event` | Delete an appointment | `calendar:write` |
| `list_tasks` | List tasks *(read-only)* | `tasks:read` |
| `get_task` | Get a task *(read-only)* | `tasks:read` |
| `create_task` | Create a task | `tasks:write` |
| `update_task` | Change a task | `tasks:write` |
| `complete_task` | Complete a task | `tasks:write` |
| `reopen_task` | Reopen a task | `tasks:write` |
| `delete_task` | Delete a task | `tasks:write` |
| `list_lists` | List lists *(read-only)* | `lists:read` |
| `create_list` | Create a list | `lists:write` |
| `update_list` | Rename a list | `lists:write` |
| `delete_list` | Delete a list | `lists:write` |
| `list_items` | List items *(read-only)* | `lists:read` |
| `add_items` | Add items | `lists:write` |
| `update_item` | Change or tick off an item | `lists:write` |
| `delete_item` | Remove an item | `lists:write` |
| `list_documents` | List and search documents *(read-only)* | `documents:read` |
| `get_document` | Get a document *(read-only)* | `documents:read` |
| `upload_document` | Upload a document | `documents:write` |
| `update_document` | Change a document | `documents:write` |
| `analyze_document` | Analyse a document with AI | `documents:write` |
| `delete_document` | Delete a document | `documents:write` |
| `search` | Smart search *(read-only)* | `search` |
| `ask_butler` | Ask the butler | `butler` |

## Tips

- Tell the assistant which workspace you mean ("in Familie Berger"); it starts with `list_workspaces`.
- `ask_butler` and `analyze_document` use the workspace owner's AI credits.
- Files: `upload_document` takes the file as base64 (up to about 10 MB). Downloading files is only possible through the REST API.