Mcp

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

GET
POST
GET
POST
GET
POST
GET
POST
GET
GET
POST

List all mcp analytics feedback

List MCP feedback submissions for the current project, newest first.

Required API key scopes

mcp_analytics:read

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/mcp_analytics/feedback
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/mcp_analytics/feedback/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "kind": "feedback",
      "goal": "string",
      "summary": "string",
      "category": "string",
      "blocked": true,
      "attempted_tool": "string",
      "mcp_client_name": "string",
      "mcp_client_version": "string",
      "mcp_protocol_version": "string",
      "mcp_transport": "string",
      "mcp_session_id": "string",
      "mcp_trace_id": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create mcp analytics feedback

Create a new MCP feedback submission for the current project.

Required API key scopes

mcp_analytics:write

Request parameters

  • attempted_tool
    string
    Default:
  • mcp_client_name
    string
    Default:
  • mcp_client_version
    string
    Default:
  • mcp_protocol_version
    string
    Default:
  • mcp_transport
    string
    Default:
  • mcp_session_id
    string
    Default:
  • mcp_trace_id
    string
    Default:
  • goal
    string
  • feedback
    string
  • category
    Default: other

Response


Example request

POST /api/projects/:project_id/mcp_analytics/feedback
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/mcp_analytics/feedback/\
	-d goal="string",\
	-d feedback="string"

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "kind": "feedback",
  "goal": "string",
  "summary": "string",
  "category": "string",
  "blocked": true,
  "attempted_tool": "string",
  "mcp_client_name": "string",
  "mcp_client_version": "string",
  "mcp_protocol_version": "string",
  "mcp_transport": "string",
  "mcp_session_id": "string",
  "mcp_trace_id": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve mcp analytics intent clusters

Return the most recent intent cluster snapshot for the current project. Returns an empty IDLE snapshot when no clustering run has happened yet.

Required API key scopes

mcp_analytics:read

Example request

GET /api/projects/:project_id/mcp_analytics/intent_clusters
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/mcp_analytics/intent_clusters/

Example response

Status 200
RESPONSE
{
  "status": "idle",
  "error_message": "string",
  "last_computed_at": "2019-08-24T14:15:22Z",
  "last_computed_by_email": "string",
  "clusters": [
    {
      "id": 0,
      "label": "string",
      "intent_count": 0,
      "session_count": 0,
      "call_count": 0,
      "error_count": 0,
      "error_rate_pct": 0.1,
      "routing_entropy": 0.1,
      "tool_distribution": [
        {
          "tool": "string",
          "count": 0,
          "pct": 0.1,
          "errors": 0,
          "error_rate_pct": 0.1
        }
      ],
      "sample_intents": [
        "string"
      ],
      "journey": {
        "paths": [
          {
            "steps": [
              "string"
            ],
            "outcome": "completed",
            "count": 0
          }
        ],
        "total_sessions": 0,
        "leak": {
          "steps": [
            "string"
          ],
          "outcome": "completed",
          "count": 0
        }
      }
    }
  ],
  "computed_with": {
    "distance_threshold": 0.1,
    "embedding_model": "string",
    "n_intents": 0,
    "n_clusters": 0
  }
}

Create mcp analytics intent clusters

Trigger an asynchronous recompute of the intent cluster snapshot. The task runs in the background; poll the GET endpoint for progress (status transitions to 'idle' or 'error').

Required API key scopes

mcp_analytics:write

Response


Example request

POST /api/projects/:project_id/mcp_analytics/intent_clusters/recompute
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/mcp_analytics/intent_clusters/recompute/

Example response

Status 202
RESPONSE
{
  "status": "idle",
  "error_message": "string",
  "last_computed_at": "2019-08-24T14:15:22Z",
  "last_computed_by_email": "string",
  "clusters": [
    {
      "id": 0,
      "label": "string",
      "intent_count": 0,
      "session_count": 0,
      "call_count": 0,
      "error_count": 0,
      "error_rate_pct": 0.1,
      "routing_entropy": 0.1,
      "tool_distribution": [
        {
          "tool": "string",
          "count": 0,
          "pct": 0.1,
          "errors": 0,
          "error_rate_pct": 0.1
        }
      ],
      "sample_intents": [
        "string"
      ],
      "journey": {
        "paths": [
          {
            "steps": [
              "string"
            ],
            "outcome": "completed",
            "count": 0
          }
        ],
        "total_sessions": 0,
        "leak": {
          "steps": [
            "string"
          ],
          "outcome": "completed",
          "count": 0
        }
      }
    }
  ],
  "computed_with": {
    "distance_threshold": 0.1,
    "embedding_model": "string",
    "n_intents": 0,
    "n_clusters": 0
  }
}

List all mcp analytics missing capabilities

List missing capability reports for the current project, newest first.

Required API key scopes

mcp_analytics:read

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/mcp_analytics/missing_capabilities
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/mcp_analytics/missing_capabilities/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "kind": "feedback",
      "goal": "string",
      "summary": "string",
      "category": "string",
      "blocked": true,
      "attempted_tool": "string",
      "mcp_client_name": "string",
      "mcp_client_version": "string",
      "mcp_protocol_version": "string",
      "mcp_transport": "string",
      "mcp_session_id": "string",
      "mcp_trace_id": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create mcp analytics missing capabilities

Create a new missing capability report for the current project.

Required API key scopes

mcp_analytics:write

Request parameters

  • attempted_tool
    string
    Default:
  • mcp_client_name
    string
    Default:
  • mcp_client_version
    string
    Default:
  • mcp_protocol_version
    string
    Default:
  • mcp_transport
    string
    Default:
  • mcp_session_id
    string
    Default:
  • mcp_trace_id
    string
    Default:
  • goal
    string
  • missing_capability
    string
  • blocked
    boolean
    Default: true

Response


Example request

POST /api/projects/:project_id/mcp_analytics/missing_capabilities
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/mcp_analytics/missing_capabilities/\
	-d goal="string",\
	-d missing_capability="string"

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "kind": "feedback",
  "goal": "string",
  "summary": "string",
  "category": "string",
  "blocked": true,
  "attempted_tool": "string",
  "mcp_client_name": "string",
  "mcp_client_version": "string",
  "mcp_protocol_version": "string",
  "mcp_transport": "string",
  "mcp_session_id": "string",
  "mcp_trace_id": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

List all mcp analytics sessions

List MCP sessions for the current project, derived by grouping $mcp_tool_call events by $mcp_session_id. Ordered by newest session start first by default.

Required API key scopes

mcp_analytics:read

Query parameters

  • date_from
    string
  • date_to
    string
  • limit
    integer
    Default: 100
  • offset
    integer
    Default: 0
  • order_by
    string
    Default:
  • search
    string
    Default:

Response


Example request

GET /api/projects/:project_id/mcp_analytics/sessions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/mcp_analytics/sessions/

Example response

Status 200
RESPONSE
{
  "results": [
    {
      "session_id": "string",
      "tool_calls": 0,
      "session_start": "2019-08-24T14:15:22Z",
      "session_end": "2019-08-24T14:15:22Z",
      "distinct_id_count": 0,
      "tools_used": [
        "string"
      ],
      "mcp_client_name": "string",
      "distinct_id": "string",
      "person_email": "string",
      "person_name": "string",
      "intent": "string"
    }
  ],
  "has_next": true
}

Create mcp analytics sessions generate

Generate (or return the cached) LLM summary of the agent's goal for a session, derived from its recorded $mcp_intents. The first call summarises and persists the result; subsequent calls return the stored summary.

Required API key scopes

mcp_analytics:write

Path parameters

  • id
    string

Query parameters

  • date_from
    string

Response


Example request

POST /api/projects/:project_id/mcp_analytics/sessions/:id/generate_intent
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/mcp_analytics/sessions/:id/generate_intent/

Example response

Status 200
RESPONSE
{
  "session_id": "string",
  "intent": "string"
}

Retrieve mcp analytics sessions tool

List a page of the $mcp_tool_call events that belong to a given $session_id, in chronological order.

Required API key scopes

mcp_analytics:read

Path parameters

  • id
    string

Query parameters

  • date_from
    string
  • limit
    integer
    Default: 500
  • offset
    integer
    Default: 0

Response


Example request

GET /api/projects/:project_id/mcp_analytics/sessions/:id/tool_calls
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/mcp_analytics/sessions/:id/tool_calls/

Example response

Status 200
RESPONSE
{
  "results": [
    {
      "event_id": "string",
      "timestamp": "2019-08-24T14:15:22Z",
      "tool_name": "string",
      "intent": "string",
      "is_error": true,
      "error_message": "string",
      "duration_ms": 0
    }
  ],
  "has_next": true
}

Retrieve mcp analytics sessions activity

Aggregate counters, top tools, agent clients, and the most recent tool calls for the last 30 days, computed in one request. Powers the dashboard's activity view; always computed fresh so polling callers watch data arrive.

Required API key scopes

mcp_analytics:read

Response


Example request

GET /api/projects/:project_id/mcp_analytics/sessions/activity_overview
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/mcp_analytics/sessions/activity_overview/

Example response

Status 200
RESPONSE
{
  "stats": {
    "total_calls": 0,
    "distinct_tools": 0,
    "distinct_sessions": 0,
    "distinct_clients": 0,
    "calls_with_intent": 0,
    "error_calls": 0,
    "missing_capability_reports": 0
  },
  "top_tools": [
    {
      "tool": "string",
      "calls": 0,
      "errors": 0
    }
  ],
  "clients": [
    {
      "client": "string",
      "calls": 0
    }
  ],
  "recent_calls": [
    {
      "timestamp": "2019-08-24T14:15:22Z",
      "tool": "string",
      "intent": "string",
      "is_error": true,
      "error_message": "string",
      "duration_ms": 0,
      "client_name": "string"
    }
  ]
}

Create mcp analytics sessions intent

Generate (or return the cached) LLM digest of what agents are trying to do with this MCP server, derived from the most recent recorded $mcp_intents across all sessions. Content-addressed cache: only regenerates when new intents arrive. Powers the dashboard's low-volume activity stage.

Required API key scopes

mcp_analytics:read

Response


Example request

POST /api/projects/:project_id/mcp_analytics/sessions/intent_digest
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/mcp_analytics/sessions/intent_digest/

Example response

Status 200
RESPONSE
{
  "digest": "string",
  "intent_count": 0
}
Status 503 Intent digest generation is unavailable (LLM not configured).

Community questions