# MCP Server Bridge
> Source: https://useagentos.dev/docs/core/mcp-server

AgentOS can run as a stdio MCP server bridge for MCP-capable clients. Use
this when another local AI client should call into AgentOS session
workflows through the Model Context Protocol.

The MCP bridge is an integration surface. It is separate from AgentOS's Web
UI, CLI, channels, and gateway control console.

## Requirements

The MCP SDK the bridge needs is a core AgentOS dependency, so there is no
extra to add: any install from the [Installation](https://useagentos.dev/docs/core#installation)
section of the README (for example `use-agent-os[recommended]`) includes it.

Start the AgentOS gateway:

```sh
agentos gateway run
```

Or use the managed gateway:

```sh
agentos gateway start --json
agentos gateway status
```

## Run the Bridge

```sh
agentos mcp-server run
```

By default, the bridge connects to:

```text
ws://localhost:18791/ws
```

Use a different gateway:

```sh
agentos mcp-server run --gateway ws://localhost:18792/ws
```

The command runs a stdio MCP server. Configure your MCP-capable client to launch
that command as the server process.

## Safety Notes

- Keep the gateway bound to `127.0.0.1` unless you intentionally expose it.
- Do not put provider keys or channel secrets in MCP client config examples.
- Treat the MCP client as another tool-calling surface. The same AgentOS
  permissions, tools, sessions, and gateway state still matter.

## Troubleshooting

If the bridge cannot start:

```sh
agentos gateway status
agentos doctor
```

If the command reports that the MCP SDK is missing, reinstall or upgrade
AgentOS. If the bridge starts but cannot reach AgentOS, check that the gateway
is running at the `--gateway` address (default `ws://localhost:18791/ws`, or
`AGENTOS_GATEWAY_URL` when set).

Read next:

- [Configuration](https://useagentos.dev/docs/core/configuration)
- [Tools, Approvals, and Sandbox](https://useagentos.dev/docs/core/tools-and-sandbox)
- [Operations](https://useagentos.dev/docs/core/operations)
