MCP Proxy Events

Audit logging requires the Audit Logging add-on. See Add-ons pricing for details.

Overview

MCP proxy events track the creation, configuration, and usage of Model Context Protocol proxies. These events capture proxy lifecycle operations, URL verification, OAuth flows, and connection history access. All MCP proxy events follow the base event schema with event-specific metadata documented below.

Events

mcp_proxy.create

Triggered when a user creates a new MCP proxy in a project.

Targets

targets[0]

object

required

MCP proxy target

Show properties

type

string

required

Always "mcp_proxy"

string

required

MCP proxy’s unique identifier

name

string

required

MCP proxy’s display name

metadata.project_id

string

required

Project containing this proxy

metadata.organization_id

string

required

Organization owning the project

Metadata

metadata.source

string

required

User-facing page route (e.g., /projects/{projectId}/mcp-proxies/new)

Example

{
  "action": "mcp_proxy.create",
  "occurredAt": "2025-11-02T15:30:45.123Z",
  "version": 1,
  "actor": {
    "type": "user",
    "id": "user_01J...",
    "name": "Jane Smith",
    "metadata": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "impersonator_email": "",
      "impersonator_reason": ""
    }
  },
  "targets": [
    {
      "type": "mcp_proxy",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production API Proxy",
      "metadata": {
        "project_id": "660e8400-e29b-41d4-a716-446655440000",
        "organization_id": "org_01J..."
      }
    }
  ],
  "context": {
    "location": "203.0.113.42",
    "userAgent": "Mozilla/5.0..."
  },
  "metadata": {
    "source": "/projects/660e8400-e29b-41d4-a716-446655440000/mcp-proxies/new"
  }
}

mcp_proxy.update

Triggered when a user updates an MCP proxy’s name or description.

Targets

targets[0]

object

required

MCP proxy target

Show properties

type

string

required

Always "mcp_proxy"

string

required

MCP proxy’s unique identifier

name

string

required

MCP proxy’s updated display name

metadata.name

string

required

MCP proxy’s display name (duplicate for filtering)

metadata.project_id

string

required

Project containing this proxy

metadata.organization_id

string

required

Organization owning the project

targets[1]

object

required

Project target

Show properties

type

string

required

Always "project"

string

required

Project’s unique identifier

name

string

required

Project’s display name

metadata.name

string

required

Project’s display name (duplicate for filtering)

metadata.organization_id

string

required

Organization owning the project

Metadata

metadata.source

string

required

User-facing page route (e.g., /projects/{projectId}/mcp-proxies/{id})

metadata.changes

string

required

JSON-encoded object mapping changed field names to objects containing from and to values. Maximum 500 characters (truncated if longer).

Example

{
  "action": "mcp_proxy.update",
  "targets": [
    {
      "type": "mcp_proxy",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production API Proxy v2",
      "metadata": {
        "name": "Production API Proxy v2",
        "project_id": "660e8400-e29b-41d4-a716-446655440000",
        "organization_id": "org_01J..."
      }
    },
    {
      "type": "project",
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Production",
      "metadata": {
        "name": "Production",
        "organization_id": "org_01J..."
      }
    }
  ],
  "metadata": {
    "source": "/projects/660e8400-e29b-41d4-a716-446655440000/mcp-proxies/550e8400-e29b-41d4-a716-446655440000",
    "changes": "{\"name\":{\"from\":\"Production API Proxy\",\"to\":\"Production API Proxy v2\"},\"description\":{\"from\":\"Legacy description\",\"to\":\"Updated description\"}}"
  }
}

mcp_proxy.update_status

Triggered when a user changes an MCP proxy’s status between active and paused.

Status changes to revoked trigger the mcp_proxy.revoke event instead.

Targets

Same structure as mcp_proxy.update.

Metadata

metadata.source

string

required

User-facing page route (e.g., /projects/{projectId}/mcp-proxies/{id})

metadata.status_from

string

required

Previous status value (active, paused, or revoked). Maximum 50 characters.

metadata.status_to

string

required

New status value (active or paused for this event). Maximum 50 characters.

Example

{
  "action": "mcp_proxy.update_status",
  "targets": [
    {
      "type": "mcp_proxy",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production API Proxy"
    }
  ],
  "metadata": {
    "source": "/projects/660e8400-e29b-41d4-a716-446655440000/mcp-proxies/550e8400-e29b-41d4-a716-446655440000",
    "status_from": "active",
    "status_to": "paused"
  }
}

mcp_proxy.revoke

Triggered when a user revokes an MCP proxy (status changes to revoked). Revoked proxies cannot be modified or used.

Targets

Same structure as mcp_proxy.update.

Metadata

metadata.source

string

required

User-facing page route (e.g., /projects/{projectId}/mcp-proxies/{id})

Example

{
  "action": "mcp_proxy.revoke",
  "targets": [
    {
      "type": "mcp_proxy",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production API Proxy",
      "metadata": {
        "name": "Production API Proxy",
        "project_id": "660e8400-e29b-41d4-a716-446655440000",
        "organization_id": "org_01J..."
      }
    },
    {
      "type": "project",
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Production",
      "metadata": {
        "name": "Production",
        "organization_id": "org_01J..."
      }
    }
  ],
  "metadata": {
    "source": "/projects/660e8400-e29b-41d4-a716-446655440000/mcp-proxies/550e8400-e29b-41d4-a716-446655440000"
  }
}

mcp_proxy.delete

Triggered when an MCP proxy is permanently deleted from a project.

Targets

targets[0]

object

required

MCP proxy target

Show properties

type

string

required

Always "mcp_proxy"

string

required

MCP proxy’s unique identifier

name

string

required

MCP proxy’s display name

metadata.name

string

required

MCP proxy’s display name (duplicate for filtering)

metadata.project_id

string

required

Project containing this proxy

metadata.organization_id

string

required

Organization owning the project

targets[1]

object

required

Project target

Show properties

type

string

required

Always "project"

string

required

Project’s unique identifier

name

string

required

Project’s display name

metadata.name

string

required

Project’s display name (duplicate for filtering)

metadata.organization_id

string

required

Organization owning the project

Metadata

metadata.source

string

required

User-facing page route (e.g., /projects/{projectId}/mcp-proxies/mcp123)

Example

{
  "action": "mcp_proxy.delete",
  "occurredAt": "2025-11-02T16:45:30.123Z",
  "version": 1,
  "actor": {
    "type": "user",
    "id": "user_01J...",
    "name": "Jane Smith",
    "metadata": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "impersonator_email": "",
      "impersonator_reason": ""
    }
  },
  "targets": [
    {
      "type": "mcp_proxy",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production API Proxy",
      "metadata": {
        "name": "Production API Proxy",
        "project_id": "660e8400-e29b-41d4-a716-446655440000",
        "organization_id": "org_01J..."
      }
    },
    {
      "type": "project",
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Production",
      "metadata": {
        "name": "Production",
        "organization_id": "org_01J..."
      }
    }
  ],
  "context": {
    "location": "203.0.113.42",
    "userAgent": "Mozilla/5.0..."
  },
  "metadata": {
    "source": "/projects/660e8400-e29b-41d4-a716-446655440000/mcp-proxies/abc123"
  }
}

mcp_proxy.view_details

Triggered when a user views an MCP proxy’s details page.

Targets

targets[0]

object

required

MCP proxy target

Show properties

type

string

required

Always "mcp_proxy"

string

required

MCP proxy’s unique identifier

name

string

required

MCP proxy’s display name

metadata.project_id

string

required

Project containing this proxy

metadata.organization_id

string

required

Organization owning the project

Metadata

metadata.source

string

required

User-facing page route (e.g., /projects/{projectId}/mcp-proxies/{id})

mcp_proxy.verify_url

Triggered when a user verifies an MCP server URL during proxy creation or configuration. Records connection status and authentication requirements.

Targets

targets[0]

object

required

Project target

Show properties

type

string

required

Always "project"

string

required

Project’s unique identifier

name

string

required

Project’s display name

metadata.name

string

required

Project’s display name (duplicate for filtering)

metadata.organization_id

string

required

Organization owning the project

Metadata

metadata.source

string

required

User-facing page route (e.g., /projects/{projectId}/mcp-proxies/new)

metadata.url

string

required

MCP server URL without query parameters (origin + pathname only). Maximum 200 characters.

metadata.transport_type

string

required

Transport protocol type: streamable_http or sse

metadata.headers_count

number

required

Number of custom headers provided for the verification request

metadata.status

string

required

Verification result: connected (successful), needs_auth (authentication required), or error (connection failed)

metadata.error

string

Error message if status is error, otherwise empty string. Maximum 500 characters (truncated if longer).

Example

{
  "action": "mcp_proxy.verify_url",
  "targets": [
    {
      "type": "project",
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Production",
      "metadata": {
        "name": "Production",
        "organization_id": "org_01J..."
      }
    }
  ],
  "metadata": {
    "source": "/projects/660e8400-e29b-41d4-a716-446655440000/mcp-proxies/new",
    "url": "https://api.example.com/mcp",
    "transport_type": "streamable_http",
    "headers_count": 2,
    "status": "connected",
    "error": ""
  }
}

mcp_proxy.clear_auth

Triggered when a user clears OAuth credentials for an MCP proxy. Available for proxies using Centure OAuth authentication.

Targets

Same structure as mcp_proxy.update.

Metadata

metadata.source

string

required

User-facing page route (e.g., /projects/{projectId}/mcp-proxies/{id})

Authentication sharing mode: per_user (each user has individual credentials) or shared (one set of credentials for all users)

metadata.was_creator

boolean

required

Whether the user clearing auth was the original creator of the OAuth credentials

Example

{
  "action": "mcp_proxy.clear_auth",
  "targets": [
    {
      "type": "mcp_proxy",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production API Proxy",
      "metadata": {
        "name": "Production API Proxy",
        "project_id": "660e8400-e29b-41d4-a716-446655440000",
        "organization_id": "org_01J..."
      }
    },
    {
      "type": "project",
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Production"
    }
  ],
  "metadata": {
    "source": "/projects/660e8400-e29b-41d4-a716-446655440000/mcp-proxies/550e8400-e29b-41d4-a716-446655440000",
    "auth_sharing_strategy": "per_user",
    "was_creator": true
  }
}

mcp_proxy.list_connections

Triggered when a user views the connection history for an MCP proxy. Records pagination and filter parameters.

Targets

Same structure as mcp_proxy.update.

Metadata

metadata.source

string

required

User-facing page route (e.g., /projects/{projectId}/mcp-proxies/{id})

metadata.start_date

string

ISO 8601 date string for connection history start filter, or empty string if not provided. Maximum 500 characters (truncated if longer).

metadata.end_date

string

ISO 8601 date string for connection history end filter, or empty string if not provided. Maximum 500 characters (truncated if longer).

metadata.status

string

Connection status filter value, or empty string if not provided. Maximum 50 characters.

metadata.page

string

required

Page number (as string) for paginated results

metadata.limit

string

required

Results per page (as string)

metadata.total_results

string

required

Total number of matching connections (as string)

Example

{
  "action": "mcp_proxy.list_connections",
  "targets": [
    {
      "type": "mcp_proxy",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production API Proxy"
    }
  ],
  "metadata": {
    "source": "/projects/660e8400-e29b-41d4-a716-446655440000/mcp-proxies/550e8400-e29b-41d4-a716-446655440000",
    "start_date": "2025-10-01T00:00:00.000Z",
    "end_date": "2025-11-01T23:59:59.999Z",
    "status": "success",
    "page": "1",
    "limit": "50",
    "total_results": "127"
  }
}

mcp_proxies.list

Triggered when a user views the list of MCP proxies for a project.

Targets

targets[0]

object

required

Project target

Show properties

type

string

required

Always "project"

string

required

Project’s unique identifier

name

string

required

Project’s display name

metadata.name

string

required

Project’s display name (duplicate for filtering)

metadata.organization_id

string

required

Organization owning the project

Metadata

metadata.source

string

required

User-facing page route (e.g., /projects/{projectId}/mcp-proxies)

metadata.total_proxies

string

required

Total number of MCP proxies in the project (as string)

Example

{
  "action": "mcp_proxies.list",
  "targets": [
    {
      "type": "project",
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Production",
      "metadata": {
        "name": "Production",
        "organization_id": "org_01J..."
      }
    }
  ],
  "metadata": {
    "source": "/projects/660e8400-e29b-41d4-a716-446655440000/mcp-proxies",
    "total_proxies": "3"
  }
}

mcp_proxies.complete_client_oauth

Triggered when a user completes the OAuth authorization flow for an MCP proxy. This event occurs after the user authorizes the MCP server to access their resources through Centure’s OAuth proxy.

Targets

Same structure as mcp_proxy.update.

Metadata

metadata.source

string

required

User-facing page route where OAuth flow was completed (typically an external OAuth callback URL)

Example

{
  "action": "mcp_proxies.complete_client_oauth",
  "targets": [
    {
      "type": "mcp_proxy",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production API Proxy",
      "metadata": {
        "name": "Production API Proxy",
        "project_id": "660e8400-e29b-41d4-a716-446655440000",
        "organization_id": "org_01J..."
      }
    },
    {
      "type": "project",
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Production",
      "metadata": {
        "name": "Production",
        "organization_id": "org_01J..."
      }
    }
  ],
  "metadata": {
    "source": "/mcp-clients/callback"
  }
}

Common Patterns

Lifecycle Events

MCP proxy events follow a standard lifecycle:

Creation: mcp_proxy.verify_url → mcp_proxy.create
Configuration: mcp_proxy.update (name/description changes)
OAuth Setup: mcp_proxies.complete_client_oauth (if using Centure OAuth)
Status Management: mcp_proxy.update_status (pause/resume) or mcp_proxy.revoke (permanent)
Monitoring: mcp_proxy.view_details, mcp_proxy.list_connections, mcp_proxies.list

Two-Target Pattern

Most modification events include both the MCP proxy and its parent project as targets. This allows filtering by either resource in the audit logs portal. Three events track OAuth flows:

mcp_proxy.verify_url - Initial URL verification (may detect auth requirements)
mcp_proxies.complete_client_oauth - User completes OAuth authorization
mcp_proxy.clear_auth - User removes stored OAuth credentials

View vs List Events

mcp_proxy.view_details - Single proxy details page
mcp_proxy.list_connections - Connection history for one proxy (with filters)
mcp_proxies.list - All proxies in a project (plural resource name)

Field Truncation

MCP proxy events apply truncation to prevent exceeding WorkOS field limits:

URLs: 200 characters (query parameters stripped)
Changes JSON: 500 characters
Error messages: 500 characters
Status fields: 50 characters
Standard fields: 255 characters (names, emails, etc.)

Getting started

Security Concepts

Pricing

Monitoring & Logs

​Overview

​Events

​mcp_proxy.create

​Targets

​Metadata

​Example

​mcp_proxy.update

​Targets

​Metadata

​Example

​mcp_proxy.update_status

​Targets

​Metadata

​Example

​mcp_proxy.revoke

​Targets

​Metadata

​Example

​mcp_proxy.delete

​Targets

​Metadata

​Example

​mcp_proxy.view_details

​Targets

​Metadata

​mcp_proxy.verify_url

​Targets

​Metadata

​Example

​mcp_proxy.clear_auth

​Targets

​Metadata

​Example

​mcp_proxy.list_connections

​Targets

​Metadata

​Example

​mcp_proxies.list

​Targets

​Metadata

​Example

​mcp_proxies.complete_client_oauth

​Targets

​Metadata

​Example

​Common Patterns

​Lifecycle Events

​Two-Target Pattern

​OAuth-Related Events

​View vs List Events

​Field Truncation

Overview

Events

mcp_proxy.create

Targets

Metadata

Example

mcp_proxy.update

Targets

Metadata

Example

mcp_proxy.update_status

Targets

Metadata

Example

mcp_proxy.revoke

Targets

Metadata

Example

mcp_proxy.delete

Targets

Metadata

Example

mcp_proxy.view_details

Targets

Metadata

mcp_proxy.verify_url

Targets

Metadata

Example

mcp_proxy.clear_auth

Targets

Metadata

Example

mcp_proxy.list_connections

Targets

Metadata

Example

mcp_proxies.list

Targets

Metadata

Example

mcp_proxies.complete_client_oauth

Targets

Metadata

Example

Common Patterns

Lifecycle Events

Two-Target Pattern

OAuth-Related Events

View vs List Events

Field Truncation