Connecting MCP Clients

By connecting your MCP-compatible tools to the Global Relay Archive MCP (Model Context Protocol) server, your tools, e.g. AI agents and Integrated Development Environments (IDE), can search your Archive and receive AI-generated answers with citations.

Rather than making calls to the /v1/responses endpoint and parsing response streams, you point your MCP-compatible clients at the Global Relay Archive MCP server at /v1/mcp. Your clients automatically discover the available tools, including list_archives and search_archive, which expose only the archived data the user can access, so your users can ask natural language questions directly from the tool they already work in.

Key features

Built-in integration: Any MCP-compatible client, including AI agents, IDEs, and other tools, can search your Archive by pointing your client at the MCP endpoint. There’s no REST integration to build and no response stream to parse.

Read-only by design: The available tools your MCP client can access are read-only, so a connected client can never modify or delete your archived data. list_archives shows which Archives and Functions the authenticated user can search, and search_archive answers natural language questions from the accessible archived messages.

Answers sourced from your Archive: Answers are generated from the archived data the user can access.

Sources cited: Each answer cites the archived messages that supported it as inline links, so your results are explainable and verifiable.

Access controls: The server exposes only the data from the Archive and Function the user’s token is authorized for, so access is controlled the same as the AI Assistant API.

Stateless calls: Each tool call is independent and creates no conversation, so it fits naturally into automated workflows and agentic pipelines without managing session states.

Who benefits

RoleBenefits
AI agent developersProvide agents read-only Archive access without using custom integration code.
Developers using IDEs and MCP-enabled toolsAsk natural language questions about archived communications without leaving the tool they are working in.
IT teamsCentrally manage Archive access for AI tools: one server URL, one bearer token, and access enforced per user.

Connecting to the MCP server

To connect an MCP-compatible client to the Global Relay Archive MCP server, you need:

  • An access token, i.e. bearer token, authorized for the AI Assistant API. For more information, see Authenticating with AI Assistant API.
  • The server URL: https://ai.api.globalrelay.com/v1/mcp

To connect:

  1. Point your MCP client at the server URL, providing your bearer token for authentication.
  2. Include an Accept header with both application/json and text/event-stream.

How the server communicates

The MCP server uses the Model Context Protocol over HTTP, where each request is a single JSON-RPC 2.0 message. The server responds over a Server-Sent Events stream, which pushes messages to the client as they become available, instead of sending one complete response. Most MCP clients handle both of these details automatically.

Because the server is stateless:

  • No session is created when you connect.
  • Each tool call is independent.
  • There is no conversation history between calls, so you should include all necessary details in your request.

Available tools

The Global Relay Archive MCP server offers two tools, which your MCP client discovers automatically using the MCP tools/list method. Both tools are read-only and return their result in two forms: as structuredContent (JSON your client can parse programmatically) and as the same JSON serialized in a single text content item (for clients that only read text).

list_archives

Lists the Archives and Functions the user can access. The same Archive can appear more than once, paired with a different Function.

curl -s -X POST "[Source](https://source-pill.local/group-1?keys=src-v2-source-41cf6794ba4200b8-2)" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_archives",
      "arguments": {}
    }
  }'

Response:

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\"archives\":[{\"function\":{\"id\":101,\"name\":\"Compliance\"},\"archive\":{\"id\":\"3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b\",\"name\":\"Corporate Archive\"}}]}"}],"structuredContent":{"archives":[{"function":{"id":101,"name":"Compliance"},"archive":{"id":"3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b","name":"Corporate Archive"}}]},"isError":false}}

search_archive

Searches one Archive for messages that answer a natural language request, such as finding, summarizing, or analyzing messages. Returns an answer that cites messages inline as [subject](url) links, plus the messages cited in sources.

The following table outlines the arguments to include in a search_archive call:

ArgumentWhat it doesRequired
archive_idIdentifies the Archive to query, i.e. archive.id from list_archives.Yes
function_idIdentifies the paired Function to query, i.e. function.id from list_archives.Yes
requestThe natural language question about the accessible archived messages. The question must be under 28,000 characters.Yes
user_timezoneThe time zone used to format message dates. The default is UTC.No

Working with the tools

Using the tools together, a typical workflow follows these steps:

  1. List the available Archives: Call list_archives to view the Archives and Functions the user can access. Each entry pairs an Archive with a Function.
  2. Identify the Archive and Function to search in: Pass archive.id as archive_id and function.id as function_id in your search_archive call.
  3. Send the search request: Include all necessary information in the request, including topics, dates, senders/recipients, etc., because each call is independent.
  4. Read the answer and its sources: The returned answer cites the archived messages it is based on as inline [subject](url) links. The sources array lists each cited message once, in the order it is first cited.
  5. Check whether the answer is complete: If the complete field is false, the answer was truncated. If necessary, narrow the query, e.g. a shorter date range, fewer participants, or ask for a shorter answer, and make the call again.

Because a search_archive call can take several minutes to complete, the server can send progress updates. Include params._meta.progressToken in the request so the server sends a notifications/progress message approximately every 10 seconds. If your client resets its timeout whenever it receives a progress message, it will keep waiting for the result instead of timing out.

Error handling

Tool errors

When a tool call fails, the failure is returned as a JSON-RPC result with isError: true and a message in content. Common errors include:

  • The Archive is not found or the user does not have access to the Archive.
  • The usage allowance is exceeded.
  • The request times out.

Errors do not distinguish between an Archive not being found and the user not having access to it.

Authorization errors

If a user is not permitted to use the API, they receive a 403 error rather than 401, so the MCP client does not retry authorization.