MCP OAuth Providers

MCP OAuth providers are reusable OAuth 2.0 configurations referenced by MCP servers. Each provider holds an issuer URL, audience, optional scopes, and optional introspection settings. Multiple MCP servers can reference the same provider via _mcpOAuthProviderId, avoiding duplicated OAuth configuration.

Providers support two token validation modes: JWT validation against the issuer's JWKS endpoint (default), or RFC 7662 introspection for opaque tokens when useIntrospection is enabled with clientId/clientSecret.

MCP OAuth provider schema

List MCP OAuth providers

get

/v1/mcpoauthproviders

Returns all MCP OAuth providers in the account.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

includestringOptional

Comma-separated list of fields to project into each returned record. Triggers summary projection: the response contains a minimal identity set (_id, name, plus resource-specific fields) with the requested fields added on top. Supports dot notation for nested fields. Mutually exclusive with exclude.

Example: _integrationId,disabled,lastModified

excludestringOptional

Comma-separated list of fields to strip from the default response. Unlike include, does not trigger summary projection — returns the full record with the named fields removed. Protected identity fields (e.g. name) cannot be stripped. Mutually exclusive with include.

Example: createdAt,lastModified

Responses

200

Provider list.

application/json

MCP OAuth provider object as returned by the API.

namestring · min: 1 · max: 150Required

Display name for the OAuth provider.

Example: auth.example.com

descriptionstringOptional

Description of the provider's purpose.

Example: Production Auth0 tenant for MCP servers

issuerURLstring · uriRequired

OAuth 2.0 issuer URL. Must include http:// or https:// scheme. Bare hostnames are rejected.

Example: https://auth.example.com

audiencestringRequired

Expected aud claim on incoming access tokens.

Example: https://mcp.example.com

useIntrospectionbooleanOptional

When true, opaque access tokens are validated via the issuer's RFC 7662 introspection endpoint using clientId/clientSecret. When false, only JWT tokens validated against JWKS are accepted.

Default: false

clientIdstring · nullableOptional

OAuth client ID for token introspection. Required when useIntrospection is true.

Example: my-client-id

clientSecretstring · nullableOptional

OAuth client secret for introspection. Masked as "******" in responses; sending the masked value on PUT leaves it unchanged.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_userIdstring · objectIdRead-onlyOptional

Owning user ID.

Example: 624cb0346309dc3a543733a2

204

No providers exist in the account.

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/mcpoauthproviders

GET /v1/mcpoauthproviders HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_id": "69fcae29459e338098b54257",
    "_userId": "624cb0346309dc3a543733a2",
    "name": "auth.example.com",
    "description": "Production Auth0 tenant",
    "issuerURL": "https://auth.example.com",
    "audience": "https://mcp.example.com",
    "scopes": [
      "mcp:read",
      "mcp:write"
    ],
    "useIntrospection": true,
    "clientId": "my-client-id",
    "clientSecret": "******",
    "createdAt": "2026-05-07T15:22:16.998Z",
    "lastModified": "2026-05-07T15:22:16.998Z"
  }
]

Create an MCP OAuth provider

post

/v1/mcpoauthproviders

Creates a reusable OAuth provider that MCP servers can reference via _mcpOAuthProviderId. name, issuerURL, and audience are required. Set useIntrospection: true with clientId/clientSecret to support opaque (non-JWT) tokens.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Request body for creating or updating an MCP OAuth provider. On PUT, this is a full replacement; include all fields you want to keep because omitted optional fields are cleared.

namestring · min: 1 · max: 150Required

Display name for the OAuth provider.

Example: auth.example.com

descriptionstringOptional

Description of the provider's purpose.

Example: Production Auth0 tenant for MCP servers

issuerURLstring · uriRequired

OAuth 2.0 issuer URL. Must include http:// or https:// scheme. Bare hostnames are rejected.

Example: https://auth.example.com

audiencestringRequired

Expected aud claim on incoming access tokens.

Example: https://mcp.example.com

useIntrospectionbooleanOptional

When true, opaque access tokens are validated via the issuer's RFC 7662 introspection endpoint using clientId/clientSecret. When false, only JWT tokens validated against JWKS are accepted.

Default: false

clientIdstring · nullableOptional

OAuth client ID for token introspection. Required when useIntrospection is true.

Example: my-client-id

clientSecretstring · nullableOptional

OAuth client secret for introspection. Masked as "******" in responses; sending the masked value on PUT leaves it unchanged.

Responses

201

Created provider.

application/json

MCP OAuth provider object as returned by the API.

namestring · min: 1 · max: 150Required

Display name for the OAuth provider.

Example: auth.example.com

descriptionstringOptional

Description of the provider's purpose.

Example: Production Auth0 tenant for MCP servers

issuerURLstring · uriRequired

OAuth 2.0 issuer URL. Must include http:// or https:// scheme. Bare hostnames are rejected.

Example: https://auth.example.com

audiencestringRequired

Expected aud claim on incoming access tokens.

Example: https://mcp.example.com

useIntrospectionbooleanOptional

When true, opaque access tokens are validated via the issuer's RFC 7662 introspection endpoint using clientId/clientSecret. When false, only JWT tokens validated against JWKS are accepted.

Default: false

clientIdstring · nullableOptional

OAuth client ID for token introspection. Required when useIntrospection is true.

Example: my-client-id

clientSecretstring · nullableOptional

OAuth client secret for introspection. Masked as "******" in responses; sending the masked value on PUT leaves it unchanged.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_userIdstring · objectIdRead-onlyOptional

Owning user ID.

Example: 624cb0346309dc3a543733a2

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

post/v1/mcpoauthproviders

POST /v1/mcpoauthproviders HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 137

{
  "name": "auth.example.com",
  "issuerURL": "https://auth.example.com",
  "audience": "https://mcp.example.com",
  "scopes": [
    "mcp:read",
    "mcp:write"
  ]
}

{
  "_id": "69fcae29459e338098b54257",
  "_userId": "624cb0346309dc3a543733a2",
  "name": "auth.example.com",
  "description": "",
  "issuerURL": "https://auth.example.com",
  "audience": "https://api.example.com",
  "useIntrospection": true,
  "clientId": "cid123",
  "clientSecret": "******",
  "createdAt": "2026-05-07T15:22:16.998Z",
  "lastModified": "2026-05-07T15:22:16.998Z"
}

Get an MCP OAuth provider

get

/v1/mcpoauthproviders/{_id}

Returns the full configuration of an MCP OAuth provider.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Provider ID.

Example: 69fcae29459e338098b54257

Responses

200

Provider configuration.

application/json

MCP OAuth provider object as returned by the API.

namestring · min: 1 · max: 150Required

Display name for the OAuth provider.

Example: auth.example.com

descriptionstringOptional

Description of the provider's purpose.

Example: Production Auth0 tenant for MCP servers

issuerURLstring · uriRequired

OAuth 2.0 issuer URL. Must include http:// or https:// scheme. Bare hostnames are rejected.

Example: https://auth.example.com

audiencestringRequired

Expected aud claim on incoming access tokens.

Example: https://mcp.example.com

useIntrospectionbooleanOptional

When true, opaque access tokens are validated via the issuer's RFC 7662 introspection endpoint using clientId/clientSecret. When false, only JWT tokens validated against JWKS are accepted.

Default: false

clientIdstring · nullableOptional

OAuth client ID for token introspection. Required when useIntrospection is true.

Example: my-client-id

clientSecretstring · nullableOptional

OAuth client secret for introspection. Masked as "******" in responses; sending the masked value on PUT leaves it unchanged.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_userIdstring · objectIdRead-onlyOptional

Owning user ID.

Example: 624cb0346309dc3a543733a2

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/mcpoauthproviders/{_id}

GET /v1/mcpoauthproviders/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_id": "69fcae29459e338098b54257",
  "_userId": "624cb0346309dc3a543733a2",
  "name": "auth.example.com",
  "description": "Production Auth0 tenant",
  "issuerURL": "https://auth.example.com",
  "audience": "https://mcp.example.com",
  "scopes": [
    "mcp:read",
    "mcp:write"
  ],
  "useIntrospection": true,
  "clientId": "my-client-id",
  "clientSecret": "******",
  "createdAt": "2026-05-07T15:22:16.998Z",
  "lastModified": "2026-05-07T15:22:16.998Z"
}

Update an MCP OAuth provider

put

/v1/mcpoauthproviders/{_id}

Full replacement of an MCP OAuth provider's configuration -- include all fields, not just the ones you want to change. Send clientSecret: "******" to preserve the existing secret. Changes propagate to all MCP servers referencing this provider.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Provider ID.

Example: 69fcae29459e338098b54257

Body

Request body for creating or updating an MCP OAuth provider. On PUT, this is a full replacement; include all fields you want to keep because omitted optional fields are cleared.

namestring · min: 1 · max: 150Required

Display name for the OAuth provider.

Example: auth.example.com

descriptionstringOptional

Description of the provider's purpose.

Example: Production Auth0 tenant for MCP servers

issuerURLstring · uriRequired

OAuth 2.0 issuer URL. Must include http:// or https:// scheme. Bare hostnames are rejected.

Example: https://auth.example.com

audiencestringRequired

Expected aud claim on incoming access tokens.

Example: https://mcp.example.com

useIntrospectionbooleanOptional

When true, opaque access tokens are validated via the issuer's RFC 7662 introspection endpoint using clientId/clientSecret. When false, only JWT tokens validated against JWKS are accepted.

Default: false

clientIdstring · nullableOptional

OAuth client ID for token introspection. Required when useIntrospection is true.

Example: my-client-id

clientSecretstring · nullableOptional

OAuth client secret for introspection. Masked as "******" in responses; sending the masked value on PUT leaves it unchanged.

Responses

200

Updated provider.

application/json

MCP OAuth provider object as returned by the API.

namestring · min: 1 · max: 150Required

Display name for the OAuth provider.

Example: auth.example.com

descriptionstringOptional

Description of the provider's purpose.

Example: Production Auth0 tenant for MCP servers

issuerURLstring · uriRequired

OAuth 2.0 issuer URL. Must include http:// or https:// scheme. Bare hostnames are rejected.

Example: https://auth.example.com

audiencestringRequired

Expected aud claim on incoming access tokens.

Example: https://mcp.example.com

useIntrospectionbooleanOptional

When true, opaque access tokens are validated via the issuer's RFC 7662 introspection endpoint using clientId/clientSecret. When false, only JWT tokens validated against JWKS are accepted.

Default: false

clientIdstring · nullableOptional

OAuth client ID for token introspection. Required when useIntrospection is true.

Example: my-client-id

clientSecretstring · nullableOptional

OAuth client secret for introspection. Masked as "******" in responses; sending the masked value on PUT leaves it unchanged.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_userIdstring · objectIdRead-onlyOptional

Owning user ID.

Example: 624cb0346309dc3a543733a2

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

put/v1/mcpoauthproviders/{_id}

PUT /v1/mcpoauthproviders/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 251

{
  "name": "auth.example.com",
  "description": "Production Auth0 tenant",
  "issuerURL": "https://auth.example.com",
  "audience": "https://mcp.example.com",
  "scopes": [
    "mcp:read",
    "mcp:write"
  ],
  "useIntrospection": true,
  "clientId": "my-client-id",
  "clientSecret": "******"
}

{
  "_id": "69fcae29459e338098b54257",
  "_userId": "624cb0346309dc3a543733a2",
  "name": "auth.example.com",
  "description": "Production Auth0 tenant",
  "issuerURL": "https://auth.example.com",
  "audience": "https://mcp.example.com",
  "scopes": [
    "mcp:read",
    "mcp:write"
  ],
  "useIntrospection": true,
  "clientId": "my-client-id",
  "clientSecret": "******",
  "createdAt": "2026-05-07T15:22:16.998Z",
  "lastModified": "2026-05-08T10:02:44.310Z"
}

Delete an MCP OAuth provider

delete

/v1/mcpoauthproviders/{_id}

Deletes an MCP OAuth provider. MCP servers referencing this provider via _mcpOAuthProviderId will lose their OAuth configuration.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Provider ID.

Example: 69fcae29459e338098b54257

Responses

204

Deleted.

No content

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

delete/v1/mcpoauthproviders/{_id}

DELETE /v1/mcpoauthproviders/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content