Relay

<p align="center"> <img src="assets/relay-icon.png" alt="Relay" width="80" /> </p>

<h1 align="center">Relay</h1>

<p align="center"> <strong>The integration layer for AI agents.</strong><br/> One catalog for every tool, shared across every agent you use. </p>

<p align="center"> <a href="https://www.npmjs.com/package/relay"><img src="https://img.shields.io/npm/v/relay?color=3B82F6&label=npm&style=flat-square" alt="npm version" /></a> <a href="https://github.com/gothamdev244/relay/blob/main/LICENSE"><img src="https://img.shields.io/github/license/gothamdev244/relay?color=10B981&style=flat-square" alt="license" /></a> <a href="https://discord.gg/eF29HBHwM6"><img src="https://img.shields.io/badge/discord-join-5865F2?style=flat-square&logo=discord&logoColor=white" alt="discord" /></a> </p>

---

<p align="center"> <img src="assets/demo.gif" alt="Relay CLI Demo" width="600" /> </p>

Relay is an open-source runtime that unifies your integrations — OpenAPI, GraphQL, MCP, and Google Discovery — into a single tool catalog. Connect once, use everywhere: from Claude Code and Cursor to custom agents built with the SDK.

Architecture

<p align="center"> <img src="assets/architecture.svg" alt="Relay Architecture" width="100%" /> </p>

Quick Start

npm install -g relay
relay web

Opens a local runtime with a web UI at http://127.0.0.1:4788. Add your first source and start using tools.

Use as an MCP Server

Point any MCP-compatible agent at Relay to share your tool catalog, auth, and policies across all of them.

relay mcp

Example mcp.json for Claude Code / Cursor:

{
  "mcpServers": {
    "relay": {
      "command": "relay",
      "args": ["mcp"]
    }
  }
}

SDK

Three entry points — pick the one that fits:

Import	Use case
@relay-sh/sdk	Promise-based. Scripts, quick integrations, non-Effect codebases.
@relay-sh/sdk/core	Effect-native. Full type safety, streaming, composable pipelines.
@relay-sh/sdk/testing	Mocks and utilities for writing tests against your tools.

import { createRelay } from "@relay-sh/sdk";

const relay = await createRelay();

await relay.openapi.addSpec({
  url: "https://petstore3.swagger.io/api/v3/openapi.json",
});

const tools = await relay.tools.list();
console.log(tools);

await relay.close();

Adding Sources

Relay has first-party support for OpenAPI, GraphQL, MCP, and Google Discovery. The plugin system is open to any source type.

Web UI

Open http://127.0.0.1:4788 → Add Source → paste a URL. Relay detects the type, indexes tools, and handles auth.

CLI

relay call relay openapi addSource '{
  "spec": "https://petstore3.swagger.io/api/v3/openapi.json",
  "namespace": "petstore",
  "baseUrl": "https://petstore3.swagger.io/api/v3"
}'

Using Tools

Programmatic

const matches = await tools.discover({ query: "github issues", limit: 5 });

const detail = await tools.describe.tool({
  path: matches.bestPath,
  includeSchemas: true,
});

const issues = await tools.github.issues.list({
  owner: "vercel",
  repo: "next.js",
});

CLI

relay tools search "send email"
relay call github issues create '{"owner":"octocat","repo":"Hello-World","title":"Hi"}'
relay call gmail send '{"to":"alice@example.com","subject":"Hi"}'

If an execution pauses for auth or approval:

relay resume --execution-id exec_123

CLI Reference

relay web                               Start runtime + web UI
relay daemon run | status | stop        Manage background daemon
relay mcp                               Start MCP endpoint
relay call <path...> '{"k":"v"}'        Invoke a tool by path
relay call <path...> --help             Browse namespaces and methods
relay resume --execution-id <id>        Resume paused execution
relay tools search "<query>"            Search tools by intent
relay tools sources                     List sources + tool counts
relay tools describe <path>             Show tool schema

Project Structure

apps/
  cli/            CLI (relay command)
  local/          Local runtime server
  cloud/          Hosted service
  desktop/        Desktop app
  marketing/      relay.sh website

packages/
  core/
    sdk/          Core contracts, plugin wiring, scopes, policies
    execution/    Execution engine
    config/       Configuration and scope management
    storage-*/    Storage adapters
  plugins/
    openapi/      OpenAPI plugin
    graphql/      GraphQL plugin
    mcp/          MCP plugin
    google-*/     Google Discovery plugin
  kernel/
    quickjs/      QuickJS sandboxed runtime
    deno/         Deno subprocess runtime
    ir/           IR compiler
  react/          React UI components
  hosts/
    mcp/          MCP host surface

Development

bun install
bun run dev

Dev server starts at http://127.0.0.1:4788.

bun run test          # run tests
bun run lint          # oxlint
bun run typecheck     # type checking
bun run format        # oxfmt

See CONTRIBUTING.md for full setup instructions.

License

MIT