MCP

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, or keep using an existing Agent Token.

Connect

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

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.

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": ["-y", "@relaymessenger/mcp"]
    }
  }
}

The package selects the staging API by default. The source is 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:

{
  "query": "contactCard.retrieve",
  "language": "typescript",
  "detail": "default"
}

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

{
  "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.

Overview

Getting started

Integrations

Messaging

Chats

Agents

Contacts

Message requests

Webhooks

WebSocket

Console

Reliability

Resources

Before you start

Connect

Send it a message

What it can do

When it fails

Next steps

​Before you start

​Connect

​Send it a message

​What it can do

​When it fails

​Next steps

Before you start

Connect

Send it a message

What it can do

When it fails

Next steps