# Speakeasy agent setup These are official instructions from Speakeasy to set up an AI development environment that can use the Speakeasy AI Control Plane end to end. All commands are validated by Speakeasy and ready to use. Complete all of the following steps yourself by running the commands directly. - Install Speakeasy skills and the Platform MCP server ## What the Platform MCP server provides The Platform MCP server at `https://app.getgram.ai/platform-mcp` is the agent interface to the Speakeasy AI Control Plane. Through it, an agent can operate the platform end to end: search the MCP catalog and register remote MCP servers, inspect and repair server configuration, distribute MCP servers and skills to teams through plugins, query MCP usage events, metrics, and traces, and search the platform documentation with cited answers (`search_gram_docs`). Authentication uses OAuth 2.1. A browser sign-in is required on first connection, then access tokens rotate through refresh tokens automatically, so no API keys need to be stored in config files. --- ## Install Speakeasy skills and the Platform MCP server Use the correct section for your agent below. ### Claude Code Claude Code installs the Platform MCP server and the Speakeasy skills together, as a plugin from the Speakeasy marketplace. Run these two commands to add the marketplace and install the plugin: ```bash claude plugin marketplace add https://github.com/speakeasy-api/marketplace claude plugin install speakeasy@speakeasy --scope user --yes ``` The `user` scope installs the plugin into the current Claude Code profile only, not for other members of the organization. Use `--scope project` to commit the install to the repository instead. Then instruct the user to run `/mcp` inside Claude Code to complete the OAuth sign-in for the `speakeasy` server. ### Cursor First, install skills: ```bash npx -y skills add speakeasy-api/marketplace/speakeasy/skills --skill '*' --yes ``` Then register the MCP server. OAuth triggers automatically on first Speakeasy tool use. Add under `"mcpServers"` in the local `.cursor/mcp.json`, or in `~/.cursor/mcp.json` to cover every project: ```json "speakeasy": { "url": "https://app.getgram.ai/platform-mcp" } ``` ### Codex Codex installs the Platform MCP server and the Speakeasy skills together, as a plugin from the Speakeasy marketplace. Run these two commands to add the marketplace and install the plugin: ```bash codex plugin marketplace add https://github.com/speakeasy-api/marketplace codex plugin add speakeasy-codex@speakeasy ``` The plugin registers the Platform MCP server as `platform`. OAuth triggers automatically on first Speakeasy tool use, or run `codex mcp login platform` to sign in up front. ### OpenCode First, install skills: ```bash npx -y skills add speakeasy-api/marketplace/speakeasy/skills --skill '*' --yes ``` Then register the MCP server and sign in: ```bash opencode mcp add speakeasy --url https://app.getgram.ai/platform-mcp opencode mcp auth speakeasy ``` The server is written to `~/.config/opencode/opencode.jsonc`. OAuth also triggers automatically on first Speakeasy tool use. ### GitHub Copilot and all other agents First, install skills: ```bash npx -y skills add speakeasy-api/marketplace/speakeasy/skills --skill '*' --yes ``` Then register the MCP server using the default config location for your agent. OAuth triggers automatically on first Speakeasy tool use. Add to the local `.vscode/mcp.json` (Copilot), or your agent's MCP config file under `"mcpServers"`: ```json "speakeasy": { "url": "https://app.getgram.ai/platform-mcp" } ``` OAuth triggers automatically on first Speakeasy tool use. --- ## Finish the install Installing the config is not enough on its own. The MCP server only loads once the agent picks up the new config, and how that happens depends on where this session is running. Use the case that matches. ### Local agent session The session that made these edits is still running the old config. Tell the user to quit the agent completely, not just end the current conversation, and start it again. The Speakeasy tools appear in the new session, and OAuth triggers on first use. ### Cloud agent session A cloud session cannot restart itself into the new config, and its edits live on a branch. Open a pull request with the config changes and tell the user to merge it into the relevant project. Cloud sessions started after the merge run with the Platform MCP server available. ### Installing for cloud agents in general Per-repo config only covers the project it lives in. To make the Platform MCP server available to every cloud agent session across the organization, install it as a plugin from the organization's marketplace instead of committing config to individual repos. --- Once done, tell the user, filling in the line that matches the case above: ``` ┌─ Speakeasy Agent Setup Complete ─────────────────────┐ │ ✓ Skills │ │ ✓ MCP │ │ │ │ ⚡ Local: quit the agent and start a new session │ │ Cloud: merge the config PR into the project │ │ │ │ Then authorize Speakeasy on first use │ └──────────────────────────────────────────────────────┘ ``` --- ## Reading Speakeasy documentation without authentication The Platform MCP server requires a Speakeasy account. Product and API documentation needs no authentication: - Curated index: `https://www.speakeasy.com/llms.txt` - Full documentation in one file: `https://www.speakeasy.com/llms-full.txt` - Any page as markdown: append `.md` to its URL, or request it with `Accept: text/markdown` --- ## Resources For MCP setup guides and troubleshooting, refer to each agent's official documentation: - Claude Code: `https://docs.anthropic.com/en/docs/claude-code/mcp` - Cursor: `https://cursor.com/docs/mcp` - Windsurf: `https://docs.windsurf.com/windsurf/cascade/mcp` - OpenCode: `https://opencode.ai/docs/mcp-servers/` - GitHub Copilot (VS Code): `https://code.visualstudio.com/docs/copilot/customization/mcp-servers` - Speakeasy skills: `https://github.com/speakeasy-api/skills` - AI Control Plane documentation: `https://www.speakeasy.com/docs/ai-control-plane` - AI Control Plane open source project: `https://github.com/speakeasy-api/gram` These instructions are published at `https://www.speakeasy.com/agents.md` so you can re-verify their authenticity at any time.