OpenAPI Authentication for MCP: API Keys, Bearer Tokens, and OAuth

The short answer

An OpenAPI-to-MCP connection usually has two separate authentication boundaries:

1. AI client to MCP server: proves which user or client may call the MCP endpoint.
2. MCP server to REST API: proves which upstream API operations the gateway may execute.

These boundaries may use different credentials and different protocols. An OAuth token presented by an AI client must not automatically become the token sent to the REST API.

datamcp keeps them separate. A client can authenticate to its remote MCP endpoint with a datamcp API key or OAuth 2.0 with PKCE. The OpenAPI connection separately stores the credential used for upstream API calls: no authentication, API key, Bearer token, HTTP Basic auth, and optional custom headers.

datamcp does not currently run an upstream OAuth authorization or refresh-token flow. If an API accepts a pre-issued access token, you can configure it as a Bearer token, but its issuance, expiry, and rotation remain external.

The two authentication boundaries

Keeping these boundaries separate provides three practical benefits:

• upstream credentials stay out of Cursor, ChatGPT, Claude, or another AI client
• one upstream credential can sit behind separately revocable MCP links
• changing client authentication does not require changing the REST API's security model

This separation also prevents token passthrough, where a server forwards the client's access token to a downstream API. The MCP authorization specification explicitly treats MCP servers as protected resources and requires tokens to be issued for the intended MCP server rather than accepted and relayed indiscriminately.

What OpenAPI security schemes actually describe

The OpenAPI document can declare authentication under components.securitySchemes and apply schemes with the security field. The OpenAPI 3.1 specification defines API keys, HTTP authentication, OAuth 2.0, OpenID Connect, and mutual TLS.

For example, a header API key can be described as:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
security:
  - ApiKeyAuth: []

The specification describes where and how a credential is used. It should not contain the secret value itself. The actual key, token, username, or password belongs in a secret store or connection configuration.

An OpenAPI declaration is also not proof that an MCP gateway implements every scheme. Always compare the specification with the gateway's supported connection methods.

Upstream API key authentication

API keys are common for internal services, developer APIs, and gateway-managed endpoints. OpenAPI permits API keys in a header, query string, or cookie.

datamcp supports all three locations:

• Header: X-API-Key: secret
• Query: ?api_key=secret
• Cookie: Cookie: session_key=secret

During setup, select API Key, choose the location, and enter the exact name declared by the API. The configured key is injected server-side when call_endpoint executes an approved operation.

Prefer a header when you control the API. Query-string credentials are more likely to appear in browser history, proxy logs, analytics, or copied URLs. Cookie-based keys can be necessary for an existing API, but they should still be dedicated to the integration and scoped narrowly.

Upstream Bearer token authentication

Bearer authentication sends a token in the HTTP authorization header:

Authorization: Bearer YOUR_TOKEN

In OpenAPI, it is normally described as:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
security:
  - BearerAuth: []

Configure Bearer Token in datamcp when the token already exists and the API accepts it directly. Use a token created for this integration, with the smallest useful scope and an explicit rotation process.

A Bearer token may have been issued by an OAuth server, but storing that token is not the same as implementing OAuth. datamcp currently does not redirect an administrator through the upstream API's consent screen, exchange an authorization code, or refresh an expired upstream token.

Upstream HTTP Basic authentication

HTTP Basic combines a username and password and sends the Base64-encoded result in the authorization header:

Authorization: Basic BASE64_USERNAME_AND_PASSWORD

datamcp supports Basic auth for the upstream REST API. Enter the username and password on the OpenAPI connection; the resulting header is assembled server-side.

Basic auth must only be used over verified HTTPS. Base64 is an encoding, not encryption. Prefer a dedicated service account rather than a human user's permanent credentials.

Custom headers

Some APIs require fixed context in addition to the primary credential, for example:

X-Tenant-ID: acme-production
X-API-Version: 2026-07

datamcp can add optional custom headers to upstream requests. Use them for stable integration context, not for values that should vary per tool call. Keep secrets in the primary credential fields where possible and avoid duplicating authorization values across multiple headers.

OAuth to MCP is not OAuth to the REST API

For a remote MCP endpoint, OAuth answers: may this client call this MCP server?

For an upstream REST API, OAuth answers: may this integration call this API?

The authorization servers, audiences, scopes, access tokens, and refresh lifecycles can all be different. Treating them as one flow creates confused-deputy and token-leakage risks.

datamcp supports OAuth 2.0 with PKCE for the client-to-MCP boundary. That lets a compatible AI client authorize access to the datamcp MCP endpoint without receiving the OpenAPI connection's upstream secret.

For the MCP-to-API boundary, datamcp currently accepts a pre-issued Bearer token but does not operate the upstream OAuth flow. If the API requires interactive consent, dynamic client registration, automatic refresh, token exchange, or per-user delegated scopes, use a custom MCP server or another integration layer that implements that lifecycle.

How to configure OpenAPI authentication in datamcp

Step 1: Inspect the API's security declaration

Find components.securitySchemes and the effective security requirement. Check whether authentication applies globally or only to specific operations.

Record:

• scheme type
• credential location
• parameter or header name
• required scopes
• token expiry and rotation owner
• operations the credential may access

Step 2: Choose a supported upstream method

Map the API requirement to the current connection options:

Step 3: Create and validate the OpenAPI connection

Open Connections, create an OpenAPI connection, and paste a public OpenAPI 3.x JSON/YAML URL or a supported Swagger UI or Redoc URL.

Choose the upstream authentication method and enter the connection credential. If needed, add fixed custom headers. datamcp validates the specification and can detect declared auth metadata, but you remain responsible for confirming the credential's scope.

The specification URL itself must currently be publicly fetchable. Connection credentials authenticate live upstream API calls, not private documentation downloads.

Step 4: Choose the MCP access policy

Create a Read Only MCP link for GET and HEAD operations, or a Full Access link when the client genuinely needs write methods.

This policy is separate from upstream authorization. A powerful upstream credential behind a Read Only link still cannot be used through datamcp for POST, PUT, PATCH, or DELETE. Conversely, Full Access does not grant permissions the upstream credential lacks.

Step 5: Choose client-to-MCP authentication

Configure the compatible AI client using the generated remote MCP endpoint and the supported datamcp authentication flow:

• API key for clients that accept a Bearer authorization header in MCP configuration
• OAuth with PKCE for compatible clients that support remote MCP authorization

Do not copy the upstream API key, Bearer token, username, or password into the AI client's MCP settings.

Step 6: Test discovery before execution

Start with the four OpenAPI MCP tools in this order:

1. list_api_endpoints
2. get_endpoint_details
3. get_api_schema when a component model is relevant
4. call_endpoint for one harmless approved request

Review activity after the test and confirm that a revoked or rotated credential fails as expected.

Troubleshooting 401 and 403 responses

A header API key returns 401

Check the exact header name and capitalization expected by the API. Confirm the key is configured as header, not query or cookie, and that no custom header overwrites the authorization value.

A query or cookie API key is ignored

Verify the OpenAPI in value and parameter name. api_key, key, and session_key are not interchangeable unless the API explicitly supports them.

A Bearer token suddenly stops working

Check expiry, audience, scope, revocation, and environment. Replace the token in the connection after rotating it; datamcp does not currently refresh an upstream OAuth token automatically.

Basic auth works locally but not through the API gateway

Confirm the gateway preserves the Authorization header and that the service account is permitted in the target environment. Never test Basic auth over plain HTTP.

The specification declares multiple security schemes

OpenAPI can express alternatives or combinations. datamcp stores one primary upstream auth configuration plus optional fixed custom headers; it does not orchestrate arbitrary multi-step authentication. Confirm the actual runtime requirement rather than assuming every declared scheme must be sent together.

MCP authentication succeeds but the API call fails

That is evidence the two boundaries are working independently. The client is allowed to call the MCP endpoint, while the upstream credential is missing, expired, incorrectly placed, or insufficient for the selected REST operation.

Production checklist

• keep MCP client credentials and upstream API credentials separate
• start with a Read Only MCP link
• use a dedicated upstream service credential
• choose the exact API key location and parameter name
• use verified HTTPS for every authenticated API
• document token expiry and rotation ownership
• avoid query-string secrets when a header is available
• do not place secrets in the OpenAPI document
• test both successful calls and expected denials
• review activity and test revocation before production use

Next steps

Use the OpenAPI to MCP product page to review the hosted architecture, follow the Swagger to MCP tutorial for the complete connection workflow, and keep the OpenAPI connection documentation open while configuring credentials.

For the broader control plane, read what an MCP gateway controls: authentication is only one layer alongside permission policy, credential isolation, routing, source-specific logging boundaries, and revocation.