MCP

The Model Context Protocol (MCP) is a standard interface that AI agents use to interact with ION. Agents like OpenAI Codex, Claude, and Cursor connect to the ION MCP server. A connected agent can query and act on your ION data in natural language. You can also build custom agents on top of ION with SDKs such as the AWS Strands SDK.

​

Authentication

The MCP server uses OAuth 2.1 dynamic client registration (DCR). You sign in with your existing ION account, and the agent acts with that account’s permissions.

​

MCP server URLs

Each ION region runs its own MCP server. Connect to the server for the region whose app URL you sign in to. The other regions’ servers don’t accept your ION account. For your region’s other URLs, see ION environments. The examples use the US sandbox URL. Replace it with the URL for your region and environment.

​

Connect Claude

You need a Claude Pro plan or above to connect to the ION MCP server.

1. In Claude, go to Your Profile > Settings > Connectors. Click Add custom connector.
2. Enter a name and the MCP server URL for your region. For example, use the name ION-SANDBOX and the URL https://mcp.staging.buildwithion.com/mcp.
3. Click Connect. Claude prompts you to sign in to ION.
4. Ask Claude for a list of things it can do in ION. This confirms the connection and shows you its capabilities.

​

Connect Cursor

1. Open Cursor and go to Cursor Settings.
2. Click Tools and MCP > Add an MCP Server.
3. Enter this configuration. Swap the name and URL for your region and environment. You can add more than one:
   {
     "mcpServers": {
       "ion": {
         "url": "https://mcp.staging.buildwithion.com/mcp"
       }
     }
   }
   
4. Turn on Agent mode. The chat window starts in Ask mode, which doesn’t allow MCP servers.
5. Ask Cursor for a list of things it can do in ION. This confirms the connection and shows you its capabilities.

​

Connect OpenAI Codex

You need OpenAI Codex installed and signed in to connect to the ION MCP server.

1. In your terminal, add the ION MCP server with the MCP server URL for your region:
   codex mcp add ion --url https://mcp.staging.buildwithion.com/mcp
   
2. Sign in to ION through Codex:
   codex mcp login ion
   
3. Complete the ION sign-in flow in your browser.
4. Run codex mcp list, or use /mcp in the Codex terminal UI, to confirm the server is connected.
5. Ask Codex for a list of things it can do in ION. This confirms the connection and shows you its capabilities.

Codex stores MCP server configuration in ~/.codex/config.toml. The Codex CLI and Codex IDE extension use the same configuration.