Sign in
mcp-integrations

Create a new custom MCP integration

post/mcp-integrations/custom

Request

  • The document declares no server URL.
  • Auth: none declared

Request body

namestring required
serverUrlstring required
orgConfigValuesobject required
returnsPiiboolean

Example request

{
  "name": "My Custom MCP Server",
  "serverUrl": "https://my-mcp-server.example.com/mcp",
  "configSchema": {
    "authType": "CUSTOM",
    "orgFields": [
      {
        "key": "personalToken",
        "label": "Personal access token",
        "type": "secret",
        "headerName": "Authorization",
        "prefix": "Bearer ",
        "required": true,
        "help": "Create a token in your profile."
      }
    ],
    "userFields": [
      {
        "key": "personalToken",
        "label": "Personal access token",
        "type": "secret",
        "headerName": "Authorization",
        "prefix": "Bearer ",
        "required": true,
        "help": "Create a token in your profile."
      }
    ],
    "oauth": {
      "clientRegistration": "automatic",
      "scopes": [
        "documents:read"
      ]
    }
  },
  "oauthClient": {
    "clientId": "ayunis-core-client",
    "clientSecret": "client-secret"
  },
  "orgConfigValues": {
    "tenantId": "council-42"
  },
  "returnsPii": true
}

Response

Integration created successfully

idstring required

Unique identifier of the integration

namestring required

Name of the integration

type'predefined' | 'custom' | 'marketplace' required

Type of integration

slugstring

Predefined integration slug (only for predefined integrations)

serverUrlstring

Custom server URL (only for custom integrations)

enabledboolean required

Whether the integration is enabled

organizationIdstring required

Organization that owns this integration

authMethod'NO_AUTH' | 'BEARER_TOKEN' | 'CUSTOM_HEADER' | 'OAUTH'

Authentication method used

authHeaderNamestring

Custom auth header name

hasCredentialsboolean required

Whether credentials are configured (never exposes actual credentials)

connectionStatus'connected' | 'disconnected' | 'error' | 'unknown'

Connection status of the integration

lastConnectionErrorstring

Last error message if connection failed

lastConnectionCheckstring date-time

Timestamp of the last connection check

createdAtstring date-time required

Timestamp when the integration was created

updatedAtstring date-time required

Timestamp when the integration was last updated

returnsPiiboolean required

Whether tools from this integration may return PII data that should be anonymized in anonymous mode

marketplaceIdentifierstring

Marketplace integration identifier (only for marketplace integrations)

configSchemaobject

Configuration schema for marketplace and schema-configured custom integrations

oauthClientConfiguredboolean

Whether a static OAuth client has been configured

hasUserFieldsboolean

Whether this integration has user-level config fields

userAuthorizationRequiredboolean

Whether this integration requires each individual user to provide their own credentials before they can use it (has required user-level fields).

userAuthorizedboolean

Whether the current user has satisfied the per-user authorization requirement. Only populated on per-user endpoints (e.g. the available integrations list); undefined elsewhere.

orgConfigValuesobject

Current org-level config values for schema-configured integrations. Non-secret fields contain plaintext values. Secret fields are masked with "••••••".

logoUrlstring nullable

Logo URL for marketplace integrations

descriptionstring

Human-readable description of the integration (populated from marketplace shortDescription or predefined config description)

Example response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Production Test Integration",
  "type": "predefined",
  "slug": "TEST",
  "serverUrl": "https://my-server.com/mcp",
  "enabled": true,
  "organizationId": "123e4567-e89b-12d3-a456-426614174001",
  "authMethod": "BEARER_TOKEN",
  "authHeaderName": "Authorization",
  "hasCredentials": true,
  "connectionStatus": "connected",
  "lastConnectionError": "Failed to reach server: Connection timeout",
  "lastConnectionCheck": "2025-10-28T14:30:00.000Z",
  "createdAt": "2025-10-28T10:00:00.000Z",
  "updatedAt": "2025-10-28T12:30:00.000Z",
  "returnsPii": true,
  "marketplaceIdentifier": "oparl-council-data",
  "userAuthorizationRequired": true,
  "orgConfigValues": {
    "endpointUrl": "https://example.com/api",
    "apiToken": "••••••"
  },
  "logoUrl": "https://marketplace.ayunis.com/logos/oparl.png",
  "description": "Access municipal council data via OParl"
}

Changes

No recorded changes to this operation across all 51 revisions of this API.