Tray Headless MCP

Connect any MCP-compatible client — Cursor, Codex, Windsurf, or your own agent — to the hosted Tray MCP server at api.tray.io/mcp.

Tray Headless MCP is a hosted MCP server at api.tray.io/mcp that exposes the Tray platform as MCP tools over HTTP. There's nothing to install or run — it's a remote endpoint your MCP client connects to.

It exposes the same capability surface as the Claude Code plugin: build and edit workflows, projects, connectors, authentication, validation, and run and debug. The plugin is one client of this server, with a guided build process, skills, research subagent, and workspace pinning layered on top. The raw server gives you the tools, and you (or your agent) drive them.

These tools act in your Tray workspace as you

Once you complete the OAuth2 sign-in, the server's tools operate with your Tray identity and permissions. They can create, modify, and delete projects, workflows, and authentications, and run workflows that have real side effects — every call is made as you, scoped to what your account can access, against the workspace you pass. The packaged plugin surfaces destructive actions for confirmation; a raw client applies only the guardrails you give it, so review what your agent is allowed to do.

Who it's for

Anyone working in an MCP-compatible client other than the packaged Claude Code plugin — for example Cursor, Codex, Windsurf, Claude Code configured by hand, or a custom agent you're building. Use it when you want Tray's platform tools available to your own AI workflow.

How to connect

api.tray.io/mcp is a Streamable HTTP MCP server that uses interactive OAuth2. Add it to your client's MCP configuration, then complete a one-time browser sign-in to Tray — there's no token to generate or carry.

Two things to keep in mind:

Don't add an Authorization header. Supplying a static token switches the client into token-based auth and prevents the interactive OAuth2 sign-in.
Supply your Workspace ID. Most Tray platform calls are workspace-scoped and take a Workspace ID per call, so pass it to your client or agent. (The packaged plugin pins this for you; raw clients pass it explicitly.)

Add Tray to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "tray": {
      "url": "https://api.tray.io/mcp"
    }
  }
}

Then open Cursor's settings, find the tray server under Tools and MCP, and click Needs login to complete the browser sign-in.

Add Tray to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "tray": {
      "serverUrl": "https://api.tray.io/mcp"
    }
  }
}

Windsurf uses serverUrl (not url) for remote servers. After adding it, complete the authorize prompt that appears in the MCP panel to sign in. Use a recent Windsurf build for the smoothest OAuth experience.

Add Tray to ~/.codex/config.toml:

[mcp_servers.tray]
url = "https://api.tray.io/mcp"

Then authenticate from the CLI:

codex mcp login tray

This opens the browser sign-in. Remote MCP servers with OAuth require a recent version of the Codex CLI.

For Claude Code, the Tray Headless for Claude Code plugin is the recommended path — it adds the guided build process, skills, research subagent, and workspace pinning. Configure the raw server by hand only if you specifically want the tools without the plugin layer.

Add the server with the CLI:

claude mcp add --transport http tray https://api.tray.io/mcp

Then run /mcp inside a session and follow the browser sign-in to authorize.

The exact configuration keys vary slightly by client; the snippets above are the verified shape for each. For a side-by-side comparison of the plugin and the standalone server, see the Tray Headless overview.