Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

2.5 KB
Raw Blame
---
title: "beacon mcp serve"
description: "Run the local Beacon MCP server"
---

## Command overview

`beacon mcp serve` starts the local Beacon MCP server over stdio or loopback HTTP JSON-RPC.

```bash title="Command syntax"
beacon mcp serve
```

The server reads the configured Beacon runtime JSONL log and the approved-memory
store next to the endpoint log base directory. It exposes compact activity tools
plus read-only approved-memory tools to MCP clients. Use stdio for clients that
launch Beacon as a subprocess. Use HTTP only for local loopback testing or local
tools that connect to a running server.

Registered tools:

- `search_activity`
- `summarize_activity`
- `get_activity_event`
- `list_activity_filters`
- `search_memory`
- `get_memory`
- `get_memory_context`

## Flags

| Flag | Description |
|------|-------------|
| `--user` | Use per-user endpoint paths. Enabled by default |
| `--system` | Use system endpoint paths |
| `--log-path PATH` | Runtime JSONL log path |
| `--transport stdio\|http` | MCP transport. Defaults to `stdio` |
| `--addr ADDR` | Loopback HTTP JSON-RPC listen address for `--transport http`. Defaults to `127.0.0.1:8766` |

## Examples

Run over stdio for desktop MCP clients:

```bash title="Run over stdio for desktop MCP clients"
beacon mcp serve --transport stdio
```

Example stdio client configuration:

```json
{
  "mcpServers": {
    "beacon": {
      "command": "beacon",
      "args": ["mcp", "serve", "--transport", "stdio"]
    }
  }
}
```

Run over loopback HTTP JSON-RPC:

```bash title="Run over loopback HTTP JSON-RPC"
beacon mcp serve --transport http --addr 127.0.0.1:8766
```

Use a specific runtime log:

```bash title="Use a specific runtime log"
beacon mcp serve --log-path /path/to/runtime.jsonl
```

## HTTP endpoints

| Path | Description |
|------|-------------|
| `/mcp` | MCP JSON-RPC endpoint |
| `/health` | Local health check endpoint |

<Warning>
  Do not bind HTTP transport to a non-loopback interface. Beacon MCP is designed for local activity inspection, not remote administration.
</Warning>

## Related

<Columns cols={2}>
  <Card title="beacon mcp" icon="server" href="/cli/mcp">
    Review MCP tools, filters, and command group behavior.
  </Card>
  <Card title="beacon mcp doctor" icon="stethoscope" href="/cli/mcp-doctor">
    Validate local Beacon MCP setup before connecting a client.
  </Card>
  <Card title="Connect Cursor and Claude Code" icon="plug" href="/guides/local-testing/mcp#4-connect-cursor-and-claude-code">
    Install Beacon MCP in local assistant clients.
  </Card>
</Columns>