> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centure.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Proxy Events

> Audit log events for MCP proxy configuration, OAuth flows, and connection tracking

<Info>
  Audit logging requires the Audit Logging add-on. See [Add-ons pricing](/pricing/add-ons) for details.
</Info>

## 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](/logs/audit-events#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

<ResponseField name="targets[0]" type="object" required>
  MCP proxy target

  <Expandable title="properties">
    <ResponseField name="type" type="string" required>
      Always `"mcp_proxy"`
    </ResponseField>

    <ResponseField name="id" type="string" required>
      MCP proxy's unique identifier
    </ResponseField>

    <ResponseField name="name" type="string" required>
      MCP proxy's display name
    </ResponseField>

    <ResponseField name="metadata.project_id" type="string" required>
      Project containing this proxy
    </ResponseField>

    <ResponseField name="metadata.organization_id" type="string" required>
      Organization owning the project
    </ResponseField>
  </Expandable>
</ResponseField>

#### Metadata

<ResponseField name="metadata.source" type="string" required>
  User-facing page route (e.g., `/projects/{projectId}/mcp-proxies/new`)
</ResponseField>

#### Example

```json theme={null}
{
  "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

<ResponseField name="targets[0]" type="object" required>
  MCP proxy target

  <Expandable title="properties">
    <ResponseField name="type" type="string" required>
      Always `"mcp_proxy"`
    </ResponseField>

    <ResponseField name="id" type="string" required>
      MCP proxy's unique identifier
    </ResponseField>

    <ResponseField name="name" type="string" required>
      MCP proxy's updated display name
    </ResponseField>

    <ResponseField name="metadata.name" type="string" required>
      MCP proxy's display name (duplicate for filtering)
    </ResponseField>

    <ResponseField name="metadata.project_id" type="string" required>
      Project containing this proxy
    </ResponseField>

    <ResponseField name="metadata.organization_id" type="string" required>
      Organization owning the project
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="targets[1]" type="object" required>
  Project target

  <Expandable title="properties">
    <ResponseField name="type" type="string" required>
      Always `"project"`
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Project's unique identifier
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Project's display name
    </ResponseField>

    <ResponseField name="metadata.name" type="string" required>
      Project's display name (duplicate for filtering)
    </ResponseField>

    <ResponseField name="metadata.organization_id" type="string" required>
      Organization owning the project
    </ResponseField>
  </Expandable>
</ResponseField>

#### Metadata

<ResponseField name="metadata.source" type="string" required>
  User-facing page route (e.g., `/projects/{projectId}/mcp-proxies/{id}`)
</ResponseField>

<ResponseField name="metadata.changes" type="string" required>
  JSON-encoded object mapping changed field names to objects containing `from` and `to` values. Maximum 500 characters (truncated if longer).
</ResponseField>

#### Example

```json theme={null}
{
  "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`.

<Note>
  Status changes to `revoked` trigger the `mcp_proxy.revoke` event instead.
</Note>

#### Targets

Same structure as [`mcp_proxy.update`](#mcp-proxy-update).

#### Metadata

<ResponseField name="metadata.source" type="string" required>
  User-facing page route (e.g., `/projects/{projectId}/mcp-proxies/{id}`)
</ResponseField>

<ResponseField name="metadata.status_from" type="string" required>
  Previous status value (`active`, `paused`, or `revoked`). Maximum 50 characters.
</ResponseField>

<ResponseField name="metadata.status_to" type="string" required>
  New status value (`active` or `paused` for this event). Maximum 50 characters.
</ResponseField>

#### Example

```json theme={null}
{
  "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`](#mcp_proxyupdate).

#### Metadata

<ResponseField name="metadata.source" type="string" required>
  User-facing page route (e.g., `/projects/{projectId}/mcp-proxies/{id}`)
</ResponseField>

#### Example

```json theme={null}
{
  "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

<ResponseField name="targets[0]" type="object" required>
  MCP proxy target

  <Expandable title="properties">
    <ResponseField name="type" type="string" required>
      Always `"mcp_proxy"`
    </ResponseField>

    <ResponseField name="id" type="string" required>
      MCP proxy's unique identifier
    </ResponseField>

    <ResponseField name="name" type="string" required>
      MCP proxy's display name
    </ResponseField>

    <ResponseField name="metadata.name" type="string" required>
      MCP proxy's display name (duplicate for filtering)
    </ResponseField>

    <ResponseField name="metadata.project_id" type="string" required>
      Project containing this proxy
    </ResponseField>

    <ResponseField name="metadata.organization_id" type="string" required>
      Organization owning the project
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="targets[1]" type="object" required>
  Project target

  <Expandable title="properties">
    <ResponseField name="type" type="string" required>
      Always `"project"`
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Project's unique identifier
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Project's display name
    </ResponseField>

    <ResponseField name="metadata.name" type="string" required>
      Project's display name (duplicate for filtering)
    </ResponseField>

    <ResponseField name="metadata.organization_id" type="string" required>
      Organization owning the project
    </ResponseField>
  </Expandable>
</ResponseField>

#### Metadata

<ResponseField name="metadata.source" type="string" required>
  User-facing page route (e.g., `/projects/{projectId}/mcp-proxies/mcp123`)
</ResponseField>

#### Example

```json theme={null}
{
  "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

<ResponseField name="targets[0]" type="object" required>
  MCP proxy target

  <Expandable title="properties">
    <ResponseField name="type" type="string" required>
      Always `"mcp_proxy"`
    </ResponseField>

    <ResponseField name="id" type="string" required>
      MCP proxy's unique identifier
    </ResponseField>

    <ResponseField name="name" type="string" required>
      MCP proxy's display name
    </ResponseField>

    <ResponseField name="metadata.project_id" type="string" required>
      Project containing this proxy
    </ResponseField>

    <ResponseField name="metadata.organization_id" type="string" required>
      Organization owning the project
    </ResponseField>
  </Expandable>
</ResponseField>

#### Metadata

<ResponseField name="metadata.source" type="string" required>
  User-facing page route (e.g., `/projects/{projectId}/mcp-proxies/{id}`)
</ResponseField>

***

### 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

<ResponseField name="targets[0]" type="object" required>
  Project target

  <Expandable title="properties">
    <ResponseField name="type" type="string" required>
      Always `"project"`
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Project's unique identifier
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Project's display name
    </ResponseField>

    <ResponseField name="metadata.name" type="string" required>
      Project's display name (duplicate for filtering)
    </ResponseField>

    <ResponseField name="metadata.organization_id" type="string" required>
      Organization owning the project
    </ResponseField>
  </Expandable>
</ResponseField>

#### Metadata

<ResponseField name="metadata.source" type="string" required>
  User-facing page route (e.g., `/projects/{projectId}/mcp-proxies/new`)
</ResponseField>

<ResponseField name="metadata.url" type="string" required>
  MCP server URL without query parameters (origin + pathname only). Maximum 200 characters.
</ResponseField>

<ResponseField name="metadata.transport_type" type="string" required>
  Transport protocol type: `streamable_http` or `sse`
</ResponseField>

<ResponseField name="metadata.headers_count" type="number" required>
  Number of custom headers provided for the verification request
</ResponseField>

<ResponseField name="metadata.status" type="string" required>
  Verification result: `connected` (successful), `needs_auth` (authentication required), or `error` (connection failed)
</ResponseField>

<ResponseField name="metadata.error" type="string">
  Error message if `status` is `error`, otherwise empty string. Maximum 500 characters (truncated if longer).
</ResponseField>

#### Example

```json theme={null}
{
  "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`](#mcp-proxy-update).

#### Metadata

<ResponseField name="metadata.source" type="string" required>
  User-facing page route (e.g., `/projects/{projectId}/mcp-proxies/{id}`)
</ResponseField>

<ResponseField name="metadata.auth_sharing_strategy" type="string" required>
  Authentication sharing mode: `per_user` (each user has individual credentials) or `shared` (one set of credentials for all users)
</ResponseField>

<ResponseField name="metadata.was_creator" type="boolean" required>
  Whether the user clearing auth was the original creator of the OAuth credentials
</ResponseField>

#### Example

```json theme={null}
{
  "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`](#mcp-proxy-update).

#### Metadata

<ResponseField name="metadata.source" type="string" required>
  User-facing page route (e.g., `/projects/{projectId}/mcp-proxies/{id}`)
</ResponseField>

<ResponseField name="metadata.start_date" type="string">
  ISO 8601 date string for connection history start filter, or empty string if not provided. Maximum 500 characters (truncated if longer).
</ResponseField>

<ResponseField name="metadata.end_date" type="string">
  ISO 8601 date string for connection history end filter, or empty string if not provided. Maximum 500 characters (truncated if longer).
</ResponseField>

<ResponseField name="metadata.status" type="string">
  Connection status filter value, or empty string if not provided. Maximum 50 characters.
</ResponseField>

<ResponseField name="metadata.page" type="string" required>
  Page number (as string) for paginated results
</ResponseField>

<ResponseField name="metadata.limit" type="string" required>
  Results per page (as string)
</ResponseField>

<ResponseField name="metadata.total_results" type="string" required>
  Total number of matching connections (as string)
</ResponseField>

#### Example

```json theme={null}
{
  "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

<ResponseField name="targets[0]" type="object" required>
  Project target

  <Expandable title="properties">
    <ResponseField name="type" type="string" required>
      Always `"project"`
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Project's unique identifier
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Project's display name
    </ResponseField>

    <ResponseField name="metadata.name" type="string" required>
      Project's display name (duplicate for filtering)
    </ResponseField>

    <ResponseField name="metadata.organization_id" type="string" required>
      Organization owning the project
    </ResponseField>
  </Expandable>
</ResponseField>

#### Metadata

<ResponseField name="metadata.source" type="string" required>
  User-facing page route (e.g., `/projects/{projectId}/mcp-proxies`)
</ResponseField>

<ResponseField name="metadata.total_proxies" type="string" required>
  Total number of MCP proxies in the project (as string)
</ResponseField>

#### Example

```json theme={null}
{
  "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`](#mcp-proxy-update).

#### Metadata

<ResponseField name="metadata.source" type="string" required>
  User-facing page route where OAuth flow was completed (typically an external OAuth callback URL)
</ResponseField>

#### Example

```json theme={null}
{
  "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:

1. **Creation**: `mcp_proxy.verify_url` → `mcp_proxy.create`
2. **Configuration**: `mcp_proxy.update` (name/description changes)
3. **OAuth Setup**: `mcp_proxies.complete_client_oauth` (if using Centure OAuth)
4. **Status Management**: `mcp_proxy.update_status` (pause/resume) or `mcp_proxy.revoke` (permanent)
5. **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.

### OAuth-Related Events

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.)