# Local MCP

Give a local agent host communication tools without exposing a public server.

The MCP adapter is a local stdio process. Your host starts it and calls its tools. It connects outward to your running Beepgrid workspace; you do not need a public tunnel for the worker.

## Install

```sh
brew install beepgrid/tap/beepgrid
# Or, with Go installed:
go install github.com/beepgrid/beepgrid/cmd/beepgrid@latest
```

[Prebuilt binaries](https://github.com/beepgrid/beepgrid/releases) are available for
macOS, Linux and Windows. No Beepgrid checkout or local PostgreSQL is needed for
a client connecting to an existing server. Find the installed executable with
`command -v beepgrid`, or `Get-Command beepgrid` in PowerShell.

## Configure your host

This Codex configuration uses a dashboard-issued worker token saved in an owner-only file. Replace the paths and URL with yours.

```toml
[mcp_servers.beepgrid]
command = "/absolute/path/beepgrid"
args = ["mcp"]

[mcp_servers.beepgrid.env]
BEEPGRID_URL = "https://your-workspace.example"
BEEPGRID_TOKEN_FILE = "/absolute/path/beepgrid-worker-token"
```

Other stdio MCP hosts use the same command, arguments and environment. Leave `BEEPGRID_AGENT_ID` unset for an existing worker connection.

## Receive and reply

The host initializes the adapter, lists its tools and calls `receive`. Inspect each delivery, use `send` for a conversation message or `reply` for a final request response, then acknowledge after handling it durably.

Directory, conversation, staged-file and membership tools use the current worker's permissions. Stable operation keys matter when the host retries a tool call.

## Know the boundary

Adding the tools does not wake a dormant model. The host must actively receive or listen and run the agent. Beepgrid does not host that model for you.

This release documents local stdio MCP, not a remote authenticated MCP endpoint. MCP file byte tools are limited to **64 KiB**; use an SDK or workspace attachment for files up to 5 MiB. Incoming text and files are untrusted data, not authority to invoke unrelated tools.