Connect Cursor to MCP Gateway

Cursor can connect to the AISIX MCP endpoint as a remote Streamable HTTP client. It sends an AISIX caller API key, discovers only the tools that key may use, and invokes those tools through the gateway without receiving upstream server credentials.

Cursor remains responsible for selecting a model, deciding when to request a tool, obtaining any required approval, and presenting the result. This connection sends MCP tool traffic through AISIX; it does not route Cursor's model requests through the gateway. To route supported Ask-mode model requests separately, see the Cursor model integration.

This guide connects Cursor to the aggregated /mcp endpoint. You can continue from Set Up MCP Gateway, which grants the caller only everything__echo, or use an existing AISIX environment and a safe tool the caller may access.

Prerequisites

Before starting, prepare the following:

• Either complete Set Up MCP Gateway and retain AISIX_PROXY and AISIX_MCP_KEY, or obtain an AISIX proxy origin and caller API key from the team that operates the gateway. For an existing environment, export them with those variable names and choose one safe permitted tool for verification.
• Install Cursor with an agent-capable model configured.
• Make sure Cursor can reach the AISIX proxy URL. Cursor on the gateway host can use the quickstart address; a remote development environment needs an address it can reach.

The example uses workspace configuration so the connection can be reviewed with the project. Do not commit the caller API key. Cursor reads it from the environment instead.

Configure the Connection

Launch Cursor from the shell where AISIX_MCP_KEY is exported. If Cursor is already running and did not inherit this variable, close and relaunch it from that environment before testing the connection.

Create .cursor/mcp.json in the workspace. Replace the example URL with $AISIX_PROXY/mcp:

.cursor/mcp.json

{
  "mcpServers": {
    "aisix": {
      "url": "https://gateway.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AISIX_MCP_KEY}"
      }
    }
  }
}

For a connection available in every workspace, add the same object to ~/.cursor/mcp.json instead. Keep the environment variable available to every Cursor process that uses the configuration.

Open Customize → MCPs, select aisix, and enable the workspace source if it is disabled. Confirm that the local environment is connected and the selected permitted tool appears. For the Everything fixture, only everything__echo should appear.

Verify a Tool Call

The prompt below uses the Everything fixture from the setup guide. For an existing MCP server, substitute a permitted tool name, valid arguments, and an expected result. In Cursor agent chat, ask it to use the exact tool instead of relying on automatic tool selection:

Use the MCP tool everything__echo with the message "hello through AISIX". Return the tool result exactly.

Review and approve the invocation if Cursor requests confirmation. With the Everything fixture, the result should be:

Echo: hello through AISIX

Confirm the complete path:

• Cursor shows the permitted tool and does not show tools excluded by the caller's effective grant. For the fixture, only everything__echo should appear.
• AISIX MCP observability records a successful tools/call for the expected caller API key and server.
• Cursor displays the tool result returned through AISIX.

Tool discovery proves that the connection and caller grant work. It does not prove that the model will select a tool or that Cursor's approval policy permits execution, so retain the explicit tool-call test.

Troubleshoot Cursor

Symptom	Check
Cursor is disconnected	Confirm the URL ends in /mcp, the gateway is reachable from Cursor, and AISIX_MCP_KEY is present in the environment that launched it.
The workspace source is disabled	Open Customize → MCPs, select aisix, and enable the workspace source.
Cursor returns 401	Confirm AISIX_MCP_KEY contains the AISIX caller API key, not an upstream MCP credential.
The connection succeeds but no tools appear	Follow Troubleshoot Tool Access to check the server and effective grant. Then reload the server in Cursor.
The tool appears but the agent does not call it	Name the selected tool explicitly, enable it in the MCP tool list, and review Cursor's tool-approval policy. For the fixture, select everything__echo.

Next Steps

• Client Authentication: use gateway API keys, OAuth sign-in, or anonymous access for suitable trusted networks.
• Control Tool Access: grant exact tools, server patterns, or every registered tool.
• Observability: inspect MCP calls by caller, server, tool, and outcome.