Documentation

Build secure MCP surfaces from APIs and databases

Use this page as the practical setup path for Swagger to MCP Gateway: choose the source, publish a small MCP surface, test it in Gateway Chat, connect external MCP clients, then operate real tool traffic with validation and logs.

Publish an OpenAPI spec Connect a database

System map

Source to controlled MCP endpoint

Sources

OpenAPI spec

REST operations

Database scope

Tables and columns

Gateway boundary

Auth

Gateway token and owner scope

Validation

Policy before execution

Logs

Redacted tool traffic

MCP clients

Claude / Cursor

HTTP MCP config

VS Code / cURL

tools/list smoke test

Gateway Chat

Test with tool calls

Concepts

Gateway, source, surface, tool, and client.

Choose a path

OpenAPI, Database, or mixed workflows.

OpenAPI guide

Import specs and publish API tools.

Database guide

Publish safe database scopes.

Product concepts

How the Gateway fits together

The product pages explain why the Gateway exists. The docs explain the objects you configure and the sequence you use in production.

Source

A system the Gateway can publish to MCP. Today that can be a Swagger/OpenAPI REST API or a PostgreSQL/SQL Server database connection.

MCP surface

The published endpoint exposed to MCP clients. For OpenAPI this maps to an integration; for Database to MCP it maps to an owner-scoped database scope.

Tool catalog

The list of tools returned by tools/list. OpenAPI tools represent HTTP operations. Database schema tools describe metadata, while executor tools validate and run approved queries.

Gateway boundary

AI clients request tool calls, but the Gateway enforces auth, source ownership, publication state, limits, validation, redaction, and audit logging.

Choose your path

Start with the source your AI client needs

Use the source type to decide which setup path to follow. Mixed workflows can use both source kinds through separate MCP surfaces.

OpenAPI to MCP

Use this when your product already has REST endpoints and a Swagger/OpenAPI document. Start from OpenAPI to MCP.

Database to MCP

Use this when AI clients need governed schema context and validated read access over PostgreSQL or SQL Server. Start from Database to MCP.

Secure MCP Gateway

Use this mental model when comparing the Gateway with custom MCP servers. See the product overview.

OpenAPI guide

Publish a Swagger/OpenAPI API as MCP tools

The OpenAPI flow turns HTTP operations into curated MCP tools. The important work is not only import; it is deciding which operations should become agent-callable tools and writing descriptions that help the model choose correctly.

Step 1

Import the OpenAPI source

Go to Publish, paste a Swagger/OpenAPI JSON or YAML URL, set the upstream base URL if needed, and configure bearer or API key auth when the API requires it.

Step 2

Review generated tools

Inspect generated operation tools, hide unsafe endpoints, and improve descriptions so AI clients know when to call the tool, which inputs matter, and what result to expect.

Step 3

Publish and use the MCP URL

Copy the MCP endpoint and connect it with a Gateway token. Tool calls are routed through the Gateway before reaching the upstream API, so credentials and logs stay server-side.

Publish fewer tools than the API contains

Start with search, lookup, status, reporting, or support-helper operations. Hide bulk updates, deletes, refunds, token management, and broad admin routes until there is a specific reviewed workflow.

Write agent-ready descriptions

A good tool description says what the tool does, when to use it, which arguments control the result, and what safety constraint applies. Do not rely on short endpoint comments like "Gets orders."

Test with a real question

Ask Gateway Chat the same question a user would ask. If the model chooses the wrong tool or sends weak arguments, improve the tool description or hide confusing operations.

Example agent-ready OpenAPI tool contract

JSON

1{2  "name": "search_orders",3  "description": "Search approved orders by customer, status, or date range before support follow-up. Use limit to keep the result small.",4  "inputSchema": {5    "type": "object",6    "properties": {7      "customerId": { "type": "string" },8      "status": { "type": "string" },9      "fromDate": { "type": "string", "format": "date" },10      "limit": { "type": "integer", "maximum": 50 }11    },12    "required": ["status"]13  }14}

OpenAPI flow

Import, curate, publish

Paste OpenAPI URL

https://api.example.com/openapi.json

Parsed18 operationsDescriptions editableAuth server-side

get_order_by_id

GET /orders/{id}

create_support_ticket

POST /tickets

search_customers

GET /customers/search

MCP endpoint

/mcp/acme-orders

Published

OpenAPI security boundary

MCP clients do not need your upstream API key. In the recommended setup, they authenticate to the Gateway and the Gateway injects encrypted upstream credentials server-side. Tool descriptions guide model selection, but policy enforcement belongs in the Gateway and upstream API.

Database guide

Publish a database scope as safe MCP tools

Database to MCP separates schema understanding from query execution. Schema tools are metadata-only, while QueryPlan or SQL executor tools are validated before any database query runs.

Step 1

Connect PostgreSQL or SQL Server

Go to Add database, test the connection, and save it. Connection strings are encrypted and are not returned after save.

Step 2

Run metadata discovery

Discovery reads database metadata such as schemas, tables, columns, keys, and relationships. It does not read sample rows or return table data.

Step 3

Create and publish a scope

Choose the database, schema, or business domain scope. Publish only the tables and columns AI clients may use, add descriptions, then select one executor mode.

Design scopes by workflow

A small database can be one scope. A large database should usually be split into business-domain scopes such as sales, finance, support, or inventory.

Tune column permissions

Control which columns are visible, selectable, filterable, sortable, groupable, or aggregatable. Hidden and sensitive columns are blocked by default.

Use schema tools first

For database questions, Gateway Chat and external clients should inspect relevant schema_* tools before validating or executing aggregate, join, or ranking queries.

Database flow

Scope, metadata, validated execution

support_readonly

PostgreSQL scope · 3 tables published

QueryPlan

customers

9 columns · email masked

orders

8 columns · read-only

tickets

7 columns · support scope

Validation path

Every executor call is checked before SQL runs.

Schema tool

metadata only

Table boundary

published scope

Column policy

allowed columns

Execution

read-only plan

Recommended QueryPlan shape

JSON

1{2  "version": "1.0",3  "description": "Order count by status",4  "from": {5    "table": "Orders",6    "alias": "o"7  },8  "select": [9    {10      "column": {11        "tableAlias": "o",12        "column": "Status"13      },14      "alias": "Status"15    },16    {17      "aggregate": {18        "function": "COUNT",19        "tableAlias": "o",20        "column": "Id"21      },22      "alias": "OrderCount"23    }24  ],25  "groupBy": [26    {27      "tableAlias": "o",28      "column": "Status"29    }30  ],31  "orderBy": [32    {33      "alias": "OrderCount",34      "direction": "desc"35    }36  ],37  "limit": 10038}

Advanced SQL mode payload

JSON

1{2  "sql": "SELECT o.Status, COUNT(o.Id) AS OrderCount FROM sales.Orders AS o WHERE o.CreatedAt >= @fromDate GROUP BY o.Status ORDER BY OrderCount DESC LIMIT 100",3  "parameters": [4    {5      "name": "fromDate",6      "type": "date",7      "value": "2026-01-01"8    }9  ]10}

Database execution rules

QueryPlan mode is the recommended default because the payload is structured and easier to validate. SqlScript mode is advanced and conservative. A scope never publishes QueryPlan and SQL executor tools at the same time, and schema tools never return data rows.

MCP clients

Connect Claude, Cursor, VS Code, or cURL

After a surface is published, every MCP client needs the same two things: the MCP URL and a Gateway token. Use tools/list as the first smoke test before asking a model to call tools.

Client configuration

JSON

1{2  "mcpServers": {3    "gateway": {4      "type": "http",5      "url": "<MCP_URL>",6      "headers": {7        "Authorization": "Bearer <GATEWAY_TOKEN>"8      }9    }10  }11}

Smoke-test tools/list

cURL

1curl -X POST "<MCP_URL>" \2  -H "Content-Type: application/json" \3  -H "Authorization: Bearer <GATEWAY_TOKEN>" \4  -d '{5    "jsonrpc": "2.0",6    "id": "1",7    "method": "tools/list",8    "params": {}9  }'

Smoke-test a tool call

cURL

1curl -X POST "<MCP_URL>" \2  -H "Content-Type: application/json" \3  -H "Authorization: Bearer <GATEWAY_TOKEN>" \4  -d '{5    "jsonrpc": "2.0",6    "id": "2",7    "method": "tools/call",8    "params": {9      "name": "search_orders",10      "arguments": {11        "status": "open",12        "limit": 1013      }14    }15  }'

Client testing

External clients and Gateway Chat use the same surface

MCP client config

{
  "url": "<MCP_URL>",
  "headers": {
    "Authorization": "Bearer <TOKEN>"
  }
}

Gateway Chat

Tool aware

Check customer order status and summarize related support tickets.

Selected tools

orders_searchtickets_listsupport_readonly.query

Create a token

Use Gateway MCP keys for client authentication. Rotate keys when a client or environment no longer needs access.

Verify tools/list

A successful tools/list response confirms the URL, token, publication status, and source resolver are working.

Start with narrow scopes

Publish only the API operations or database tables needed for the first workflow, then expand deliberately.

MCP URL examples

OpenAPI surfaces use the integration MCP URL. Database surfaces use the account-bound surface key. In both cases, external clients call the Gateway URL with a Gateway token; they do not receive upstream API credentials or database connection strings.

Built-in chat

Talk to your MCP surfaces inside the Gateway

Gateway Chat is both a product feature and a validation tool. Use it to see whether the published surface is understandable before you hand the MCP URL to external clients.

Select published surfaces

The chat workspace can discover owner-scoped OpenAPI integrations and database scopes that are active and ready for tool calls.

Test tool choice

Ask realistic questions and confirm that the model chooses the intended OpenAPI tool or database scope. Weak descriptions usually show up here first.

Follow database call order

For database scopes, Chat inspects relevant schema_* tools, validates the QueryPlan or SQL candidate, then executes only after Gateway validation succeeds.

Use chat for fast validation

Built-in chat is the fastest way to verify that a surface is understandable and callable. For production integrations, external clients still use the MCP URL and Gateway token, but the same Gateway validation path applies.

Open Chat

Security model

Gateway enforcement rules

The Gateway is the trust boundary. LLMs and orchestration frameworks may propose actions, but Gateway validation decides what can execute and what is recorded.

OpenAPI calls

The Gateway checks integration state, account limits, publication state, upstream credential policy, and redacted logging before forwarding requests.

Database calls

Schema tools are metadata-only. QueryPlan and SQL executor tools validate scope, table, column, relationship, read-only, and owner boundaries before execution.

Secrets and redaction

Upstream API credentials, database connection strings, and sensitive values stay server-side and are redacted before log persistence.

Limits and entitlements

Plan limits, quotas, and rate controls protect backend systems as AI-driven traffic grows.

Descriptions are guidance

Tool and column descriptions help the model choose correctly, but they are not security rules. Enforce sensitive behavior with publication state, permissions, validation, and upstream policy.

Public docs stay public-safe

Do not publish private admin route maps, customer schemas, connection strings, tokens, or internal control-plane details in docs, llms files, screenshots, or prompts.

Operations

Run MCP surfaces like production traffic

Once MCP clients call real systems, the Gateway should be operated like any other production integration layer: monitored, limited, reviewed, and easy to roll back.

Usage dashboards

Track tool volume, quota pressure, latency, success rate, and failures as AI clients call tools.

Audit logs

Inspect tool calls and database validation events without exposing raw connection strings or sensitive payload values.

Change control

Pause integrations, hide tools, update descriptions, change scope permissions, or unpublish surfaces without changing MCP client code.

Operate safely

Security checks, logs, and usage signals

Gateway auth

Token checked before tools/list and callTool.

Policy validation

Scope and publication state enforced.

Redacted logs

Secrets and sensitive values are masked.

Change control

Pause, hide, or unpublish without client code changes.

Usage snapshot

Healthy

Success rate98%

Rate limit pressure42%

Quota used61%

Audit event

callTool allowed · arguments redacted · latency 284ms

Production checklist

Review before real users and real clients

Use this checklist before advertising a surface, connecting an external client, or allowing a team to depend on the MCP endpoint.

Surface is intentionally small

OpenAPI integrations expose only reviewed operations. Database surfaces expose only reviewed tables, columns, relationships, and one executor mode.

Descriptions are written for agents

Tool, table, column, and relationship descriptions explain purpose, inputs, expected result, and constraints in plain language.

Gateway Chat test is clean

Realistic questions select the expected tools, pass useful arguments, avoid hidden fields, and produce understandable results.

Credentials are server-side

External clients only hold Gateway tokens. Upstream API credentials and database connection strings are not copied into prompts, browser text, screenshots, or client configs.

Logs and limits are checked

Usage, latency, failures, quota pressure, validation errors, and redacted audit logs are visible before the surface is promoted.

Rollback path is obvious

The team knows how to hide a tool, unpublish a scope, rotate a token, or pause a surface without editing MCP client code.

Troubleshooting

Common setup checks

Most setup issues come from the MCP URL, token, publication state, or an intentionally blocked policy rule.

No tools returned

Confirm the integration or database scope is published, the MCP URL points to the right surface, and the token belongs to the owner account.

401 or auth failures

Regenerate the MCP key, update the client header, and make sure the client sends Authorization as a bearer token.

Database validation failed

Check that the table, column, relationship, and executor mode are published in the current scope. Hidden and sensitive columns are blocked by default.

Unexpected tool choice

Improve tool descriptions, hide overly broad operations, and keep scopes focused on one business workflow.

Keep public docs safe

Public docs should explain the product and usage model, not expose private control-plane endpoints, customer schema details, connection strings, or admin route maps.