Mcp

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

Endpoints

DELETE
POST
GET
POST
GET
GET
PATCH
POST
← Previous page

Delete mcp gateway servers

The team's gateway server registry. The registry is sparse: rows appear through the install/share/OAuth-start flows in views.py, or when an admin toggles an untouched catalog template here (set_template_enabled). Servers with no row follow the team config's default_servers_enabled.

Required API key scopes

project:write

Path parameters

  • id
    string

Example request

DELETE /api/projects/:project_id/mcp_gateway/servers/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/mcp_gateway/servers/:id/

Example response

Status 204 No response body

Create mcp gateway servers policies

Upsert per-tool states for a scope, returning the re-resolved catalog.

Required API key scopes

project:write

Path parameters

  • id
    string

Request parameters

  • scope_type
    Default: team
  • scope_user_id
    integer
  • scope_service_account_id
    string
  • policies
    Click to open
    array

Response


Example request

POST /api/projects/:project_id/mcp_gateway/servers/:id/policies
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_gateway/servers/:id/policies/\
	-d policies="array"

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": [
    {
      "tool_name": "string",
      "description": "string",
      "input_schema": {},
      "is_destructive": true,
      "policy_state": "approved",
      "team_state": "approved",
      "locked": true,
      "decided_by": "rule",
      "rule_name": "string",
      "rule_description": "string"
    }
  ]
}

Retrieve mcp gateway servers tools

Tool catalog with the resolved policy for a scope.

Required API key scopes

project:read

Path parameters

  • id
    string

Query parameters

  • scope_service_account_id
    string
  • scope_type
    string
    Default: team
    One of: "team""member""agent"
  • scope_user_id
    integer

Response


Example request

GET /api/projects/:project_id/mcp_gateway/servers/:id/tools
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_gateway/servers/:id/tools/

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": [
    {
      "tool_name": "string",
      "description": "string",
      "input_schema": {},
      "is_destructive": true,
      "policy_state": "approved",
      "team_state": "approved",
      "locked": true,
      "decided_by": "rule",
      "rule_name": "string",
      "rule_description": "string"
    }
  ]
}

Create mcp gateway servers set template enabled

Enable or disable a catalog template for the team (admin-only), materializing its gateway registration on the first toggle.

Required API key scopes

project:write

Request parameters

  • template_id
    string
  • enabled
    boolean

Response


Example request

POST /api/projects/:project_id/mcp_gateway/servers/set_template_enabled
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_gateway/servers/set_template_enabled/\
	-d template_id="string",\
	-d enabled="boolean"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "url": "http://example.com",
  "description": "string",
  "category": "business",
  "template_auth_type": "api_key",
  "auth_type": "api_key",
  "is_team_enabled": true,
  "icon_key": "",
  "icon_domain": "",
  "docs_url": "",
  "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  "tool_count": 0,
  "connections": [
    {
      "installation_id": "91166175-c6a9-4caf-88e9-3147ffc9c934",
      "user": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "last_used_at": "2019-08-24T14:15:22Z",
      "pending_oauth": true,
      "needs_reauth": true
    }
  ],
  "your_connection": {
    "installation_id": "91166175-c6a9-4caf-88e9-3147ffc9c934",
    "is_enabled": true,
    "pending_oauth": true,
    "needs_reauth": true,
    "last_used_at": "2019-08-24T14:15:22Z"
  },
  "agents": [
    {
      "service_account_id": "81f92c7b-60ae-411e-bc6f-e2dc93db8886",
      "user": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "scope": "personal",
      "name": "string",
      "handle": "string",
      "status": "active",
      "last_active_at": "2019-08-24T14:15:22Z",
      "granted_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      }
    }
  ],
  "revoked_user_ids": [
    0
  ],
  "is_revoked_for_you": true,
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

List all mcp gateway service accounts

PostHog's built-in agents and their MCP access grants.

The catalog is fixed. Projects can pause an agent's MCP access and grant or revoke servers, but cannot create, rename, rotate, or delete agents.

Required API key scopes

project:read

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/mcp_gateway/service_accounts
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_gateway/service_accounts/

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",
      "name": "string",
      "description": "string",
      "handle": "string",
      "agent_key": "support",
      "status": "active",
      "server_ids": [
        "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      ],
      "servers": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "shared_by": {
            "id": 0,
            "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
            "distinct_id": "string",
            "first_name": "string",
            "last_name": "string",
            "email": "user@example.com",
            "is_email_verified": true,
            "hedgehog_config": {},
            "role_at_organization": "engineering"
          },
          "scope": "personal",
          "name": "string",
          "description": "string",
          "url": "string",
          "icon_key": "string",
          "icon_domain": "string",
          "connection_state": "ready",
          "reachable": true
        }
      ],
      "last_active_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Retrieve mcp gateway service accounts

PostHog's built-in agents and their MCP access grants.

The catalog is fixed. Projects can pause an agent's MCP access and grant or revoke servers, but cannot create, rename, rotate, or delete agents.

Required API key scopes

project:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/mcp_gateway/service_accounts/:id
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_gateway/service_accounts/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "handle": "string",
  "agent_key": "support",
  "status": "active",
  "server_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "servers": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "shared_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "scope": "personal",
      "name": "string",
      "description": "string",
      "url": "string",
      "icon_key": "string",
      "icon_domain": "string",
      "connection_state": "ready",
      "reachable": true
    }
  ],
  "last_active_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Update mcp gateway service accounts

PostHog's built-in agents and their MCP access grants.

The catalog is fixed. Projects can pause an agent's MCP access and grant or revoke servers, but cannot create, rename, rotate, or delete agents.

Required API key scopes

project:write

Path parameters

  • id
    string

Request parameters

  • status

Response


Example request

PATCH /api/projects/:project_id/mcp_gateway/service_accounts/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/mcp_gateway/service_accounts/:id/\
	-d status=undefined

Example response

Status 200
RESPONSE
{
  "status": "active"
}

Create mcp gateway service accounts access

Share, or stop sharing, one gateway server with this agent.

Sharing is personal. enabled=true delegates the caller's own connection, and the agent may use it only when acting for the caller, unless the caller sends scope=team to lend it to the project's agent runs generally. Scope only ever applies to the caller's own share: it is their credential to lend, so no admin permission is involved and no member can change someone else's share. enabled=false removes the caller's own share and leaves other members' shares, and the agent's tool policies, in place.

Project admins can send all=true alongside enabled=false to remove every member's share of this server with this agent, along with the agent's tool policies for it.

Required API key scopes

project:write

Path parameters

  • id
    string

Request parameters

  • gateway_server_id
    string
  • enabled
    boolean
  • scope
    Default: personal
  • all
    boolean
    Default: false
  • policies
    Click to open
    array

Response


Example request

POST /api/projects/:project_id/mcp_gateway/service_accounts/:id/access
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_gateway/service_accounts/:id/access/\
	-d gateway_server_id="string",\
	-d enabled="boolean"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "handle": "string",
  "agent_key": "support",
  "status": "active",
  "server_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "servers": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "shared_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "scope": "personal",
      "name": "string",
      "description": "string",
      "url": "string",
      "icon_key": "string",
      "icon_domain": "string",
      "connection_state": "ready",
      "reachable": true
    }
  ],
  "last_active_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}
← Previous page