> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Search Relay SDK documentation and call the SDK through a local MCP server.

Use `search_docs` to find Relay SDK methods, then `execute` to call them for your Agent. Relay's API MCP runs as a local stdio process with exactly these two tools.

## Before you start

* An Agent Token or selected CLI profile for SDK calls.
* An MCP client that supports local stdio servers.
* Node.js `22.22.3` or newer for the local server.

Create a new Agent through your [organization's creation workflow](/agents/create-agent),
or keep using an existing Agent Token.

## Connect

Install the Relay API MCP server, or let the client run it with `npx`:

```bash theme={null}
npm install --global @relaymessenger/mcp
```

Add the local process to the client's MCP configuration. The server reads the Agent Token from the selected CLI profile or `RELAY_AGENT_TOKEN`.

```json theme={null}
{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": ["-y", "@relaymessenger/mcp"]
    }
  }
}
```

The package selects the staging API by default. The source is [packages/mcp](https://github.com/RelayMessenger/Relay-SDK/tree/main/packages/mcp). The trusted local MCP client decides when to run a tool.

## Send it a message

Ask your MCP client to inspect your Agent or perform a messaging task through these two tools.

| Tool          | Task                                                                                                      |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| `search_docs` | Search packaged SDK methods, signatures, parameters, and contract descriptions.                           |
| `execute`     | Run TypeScript or JavaScript defining `async function run(client)` with the initialized Relay SDK client. |

Call `search_docs` before writing an SDK call:

```json theme={null}
{
  "query": "contactCard.retrieve",
  "language": "typescript",
  "detail": "default"
}
```

Then call `execute` with a top-level `run(client)` function:

```json theme={null}
{
  "code": "async function run(client) { return await client.contactCard.retrieve(); }",
  "intent": "Read this agent's contact card"
}
```

Search reads the packaged documentation locally and works without a token. SDK calls use the configured Agent Token, which stays outside submitted code and tool arguments.

## What it can do

Each `execute` call has a fresh, bounded JavaScript runtime and returns `result` and `logs`. The provided client exposes SDK HTTP methods through JSON arguments and results. Raw upload streams and WebSocket callbacks belong in your external backend.

Always await SDK calls and reuse the same idempotency key for the same logical send. `execute` can change the Agent's account; the MCP client remains the security boundary.

## When it fails

* Local server will not start: confirm that the client can find `node` and `npx`, then run `relay-mcp --help`.
* A local tool call is refused: check the MCP client's permissions and the Agent Token for the intended Agent.
* An execution returns `isError: true`: read the tool error, check the SDK method with `search_docs`, and correct the call or credentials.

## Next steps

* [Save an Agent Token with the CLI](/cli/auth)
* [Read the API reference](/api-reference/overview)
* [Install Relay guidance](/integrations/skills)