What you are connecting
Claude, Cursor, VS Code, and other MCP clients should connect to the Gateway MCP endpoint, not directly to the upstream API or database.
A published Gateway surface represents either an OpenAPI integration or a database scope. The client receives the MCP URL and a Gateway token. The upstream API key, bearer credential, or database connection string stays server-side in the Gateway.
That separation is the main operational benefit. Client configuration identifies the MCP surface and authenticates the client, while the Gateway handles publication state, source ownership, validation, limits, redaction, and upstream execution.
What every MCP client needs
Different clients present configuration differently, but the required values are the same.
| Value | What it means | Where it should live |
|---|---|---|
| MCP URL | The Gateway endpoint for a published OpenAPI integration or database scope. | Client config. |
| Gateway token | The token used by the MCP client to authenticate to the Gateway. | Client secret storage or client config, depending on the client. |
| Upstream API key | The credential used by the Gateway to call the original API. | Gateway only. |
| Database connection string | The credential used by the Gateway to connect to PostgreSQL or SQL Server. | Gateway only, encrypted at rest. |
| Published tool catalog | The list of tools returned by tools/list. | Generated and curated in the Gateway. |
Run the preflight in Gateway Chat first
Before configuring an external client, prove that the published surface is understandable inside the Gateway.
- Open the published OpenAPI integration or database scope.
- Check that the MCP URL is created and the surface is active.
- Review the published tools and hide anything the AI workflow should not use.
- Rewrite weak tool descriptions before the client sees them.
- Ask two or three realistic questions in Gateway Chat and confirm the intended tool is selected.
- For database scopes, confirm schema tools are metadata-only and executor calls pass validation.
Client configuration shape
Most HTTP MCP clients need a server URL plus an Authorization header.
Exact configuration screens and file keys vary by client, so the safest documentation pattern is to describe the required connection shape and keep client-specific screenshots or steps separate. The Gateway-side contract is stable: MCP URL plus Gateway token.
Conceptual HTTP MCP client config
json{
"mcpServers": {
"swagger-to-mcp-gateway": {
"url": "https://swaggertomcp.com/mcp/{scopeKey}",
"headers": {
"Authorization": "Bearer <gateway-token>"
}
}
}
}Start with tools/list
A tools/list check catches most setup mistakes before the model starts choosing tools.
| Check | Expected result | If it fails |
|---|---|---|
| MCP URL | The client reaches the Gateway endpoint. | Check the copied URL, environment, and published scope slug. |
| Authorization | The Gateway accepts the token. | Regenerate or re-copy the Gateway token; do not use the upstream API key. |
| Publication state | The expected tools appear in tools/list. | Confirm the integration or scope is active and the tools are published. |
| Tool descriptions | Tool names and descriptions are clear enough for selection. | Edit descriptions in the Gateway before external rollout. |
| Database executor mode | Only the selected executor mode appears for the scope. | Do not publish QueryPlan and SqlScript executor tools together. |
Client-specific notes
Use the same Gateway contract across clients, but expect each client to expose MCP setup in its own interface.
| Client | What to configure | Practical note |
|---|---|---|
| Claude | Remote MCP server URL and Gateway token where supported by the client surface. | Use Gateway Chat first so Claude sees a curated catalog instead of a draft catalog. |
| Cursor | MCP server URL and auth configuration in the editor's MCP settings. | Keep tool names short and task-oriented because developers will see them during coding workflows. |
| VS Code | MCP endpoint configuration supported by the installed MCP-capable extension or built-in client surface. | Test with read-only tools first before exposing write actions to coding agents. |
| Internal agents | MCP URL, token, timeout, retry, and rate-limit behavior. | Treat agent traffic like integration traffic and log it by tool, caller, and result state. |
Common failure patterns
Most client setup issues are configuration or catalog issues, not protocol problems.
| Symptom | Likely cause | Fix |
|---|---|---|
| No tools appear | Wrong URL, unpublished surface, or invalid token. | Verify tools/list inside the Gateway and re-copy the MCP URL/token. |
| Too many tools appear | The OpenAPI integration was published without curation. | Hide low-value, admin, broad, or destructive operations. |
| The model picks the wrong tool | Descriptions are too vague or overlapping. | Rewrite descriptions with purpose, constraints, and expected result. |
| Database query is rejected | The request crosses scope, table, column, relationship, or limit policy. | Fix scope permissions or revise the question; do not bypass validation. |
| Sensitive data appears in logs | Redaction policy or result shape is too broad. | Tighten sensitive fields, mask modes, and returned result fields before rollout. |
Rollout order
Roll out a client connection in layers instead of connecting every surface at once.
- Start with one published surface and one client.
- Expose read-only or low-risk tools first.
- Confirm tool selection with realistic prompts.
- Inspect usage, latency, failures, and redacted logs.
- Add write tools only after the workflow, required arguments, and confirmation behavior are clear.
- Document which client is connected to which Gateway surface and token.
Sources and further reading
Common questions
Do clients connect to the upstream API directly?
No. Clients connect to the Gateway MCP endpoint. The Gateway routes validated calls to the upstream API or database executor.
What should I test first?
Start with tools/list. It confirms the MCP URL, token, publication state, and source resolver are working.
Should I put the upstream API key in Claude, Cursor, or VS Code?
No. The client should use a Gateway token. Upstream API keys and database connection strings should stay server-side in the Gateway.
Why test in Gateway Chat before connecting an external client?
Gateway Chat helps verify tool names, descriptions, scope design, and validation behavior before the same catalog is exposed to a third-party client.
What if different clients use different MCP config formats?
Keep the Gateway contract simple: MCP URL plus Gateway token. Then map those values into each client's current configuration format.
Can Gateway Chat replace external clients?
Gateway Chat is useful for testing and demos. Production workflows can still use external MCP clients with the same Gateway-published surfaces.