Authentication

openapi-mcp supports multiple authentication methods as defined in OpenAPI 3.x specifications. This page explains how to configure authentication for your API calls.

Supported Authentication Methods

openapi-mcp supports the following authentication methods:

• API Key - In header, query, or cookie as defined in the OpenAPI spec
• Bearer Token / OAuth2 - As an Authorization header with Bearer prefix
• Basic Authentication - As an Authorization header with Basic prefix

API Key Authentication

API key authentication is commonly used for APIs that require a key to be sent in a header, query parameter, or cookie.

Command-Line Flag

bin/openapi-mcp --api-key=your_api_key examples/fastly-openapi-mcp.yaml

Environment Variable

API_KEY=your_api_key bin/openapi-mcp examples/fastly-openapi-mcp.yaml

HTTP Header (HTTP Mode Only)

When using HTTP mode (--http=:8080), you can provide API keys via HTTP headers in your requests:

# Using X-API-Key header
curl -H "X-API-Key: your_api_key" http://localhost:8080/mcp -d '...'

# Using Api-Key header  
curl -H "Api-Key: your_api_key" http://localhost:8080/mcp -d '...'

The API key will be sent as specified in the OpenAPI spec, which might look like:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header  # or "query" or "cookie"
      name: X-API-Key  # The actual header, query parameter, or cookie name

Bearer Token Authentication

Bearer token authentication is used for OAuth2 and other token-based authentication mechanisms.

Command-Line Flag

bin/openapi-mcp --bearer-token=your_token examples/fastly-openapi-mcp.yaml

Environment Variable

BEARER_TOKEN=your_token bin/openapi-mcp examples/fastly-openapi-mcp.yaml

HTTP Header (HTTP Mode Only)

When using HTTP mode, you can provide Bearer tokens via the Authorization header:

curl -H "Authorization: Bearer your_token" http://localhost:8080/mcp -d '...'

The bearer token will be sent as an Authorization: Bearer {token} header for endpoints that require OAuth2 or HTTP bearer authentication, as defined in the OpenAPI spec:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

Basic Authentication

Basic authentication uses a username and password combination.

Command-Line Flag

bin/openapi-mcp --basic-auth=username:password examples/fastly-openapi-mcp.yaml

Environment Variable

BASIC_AUTH=username:password bin/openapi-mcp examples/fastly-openapi-mcp.yaml

HTTP Header (HTTP Mode Only)

When using HTTP mode, you can provide Basic authentication via the Authorization header:

curl -H "Authorization: Basic base64_encoded_credentials" http://localhost:8080/mcp -d '...'

The username and password will be Base64 encoded and sent as an Authorization: Basic {encoded} header for endpoints that require HTTP basic authentication, as defined in the OpenAPI spec:

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

HTTP Header Authentication (HTTP Mode)

When running openapi-mcp in HTTP mode (--http=:8080), you can provide authentication credentials via HTTP headers in your requests to the MCP server. This is particularly useful for integrating with web applications, API gateways, or other HTTP-based systems.

Header Authentication Examples

# Start HTTP server
bin/openapi-mcp --http=:8080 examples/fastly-openapi-mcp.yaml

# Make authenticated requests with headers
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{}}'

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"listServices","arguments":{}}}'

Multiple Authentication Methods

If your OpenAPI specification defines multiple authentication methods, you can provide all of them, and openapi-mcp will use the appropriate one for each endpoint based on the security requirements defined in the spec.

bin/openapi-mcp \
  --api-key=your_api_key \
  --bearer-token=your_token \
  --basic-auth=username:password \
  examples/fastly-openapi-mcp.yaml

Overriding the Base URL

In some cases, you may need to override the base URL defined in the OpenAPI spec, especially if you're testing against a different environment.

Command-Line Flag

bin/openapi-mcp --base-url=https://api.example.com examples/fastly-openapi-mcp.yaml

Environment Variable

OPENAPI_BASE_URL=https://api.example.com bin/openapi-mcp examples/fastly-openapi-mcp.yaml

Troubleshooting Authentication

If you're experiencing authentication issues, here are some tips:

• Check that you're providing the correct authentication credentials
• Verify that the OpenAPI spec correctly defines the security requirements
• Look for any error messages in the response that might indicate authentication issues
• Use the --extended flag to get more verbose output, which might help diagnose issues

{
  "OutputFormat": "structured",
  "OutputType": "json",
  "type": "error",
  "error": {
    "code": "authentication_error",
    "message": "Authentication failed",
    "details": {
      "status_code": 401
    },
    "suggestions": [
      "Check that you provided the correct API key",
      "Verify that the API key has the necessary permissions"
    ]
  }
}

Next Steps

Now that you understand how to configure authentication, you can:

• Learn about other configuration options
• Explore AI agent integration
• Understand output structure