Before you connect
Pixie MCP supports OAuth sign-in and scoped MCP keys. It is a separate, least-privilege integration from the REST API. Usehttps://app.pixiegtm.com/mcp for either method.
This guide is also served at https://app.pixiegtm.com/mcp/docs. Pixie’s OAuth discovery documents link to that address so clients can retrieve connection instructions from the MCP host.
OAuth sign-in
Any compatible remote MCP client can connect with OAuth 2.1 authorization-code flow and S256 PKCE. Configurehttps://app.pixiegtm.com/mcp; the client discovers Pixie’s protected-resource and authorization-server metadata automatically.
Pixie supports Dynamic Client Registration and HTTPS Client ID Metadata Documents. Hosted clients register HTTPS return URLs; native clients may register HTTP loopback URLs. During sign-in, HTTP loopback IP callbacks (127.0.0.0/8 or [::1]) may use a different port while keeping every other URI component identical. Hosted HTTPS and localhost callbacks must match exactly. Code redemption always requires the exact return URL used in the authorization request, including its chosen port.
Sign-in is required before Pixie retrieves client metadata. Authorization requests share a per-user limit of 30 per minute; a 429 response includes Retry-After. Allow revalidates client metadata. Deny uses the already stored, validated registration, so a metadata-host outage does not prevent cancellation.
- Ask your client to connect Pixie.
- Sign in to Pixie.
- Review the requesting app’s name, permissions, and return address.
- Choose Allow or Deny.
- Return to the client and verify access with a read-only operation such as
leadFinder.sources.
Scoped MCP keys
Clients that use keys need a named key beginning withpmcp_live_. Do not use a legacy pk_live_ REST API key at this endpoint.
- In Pixie, open Settings → API.
- Create a named key and select only the permissions the client needs.
- Copy the key immediately. Pixie shows it once and never stores the raw value.
Configure an MCP client
Use this endpoint and bearer token in a supported remote-MCP configuration:Use environment variables
Keep the endpoint and key out of the config file by reading them from the environment. Pixie does not require specific variable names—use whatever your client interpolates. Only the URL and theAuthorization: Bearer header are required.
First export the values. Set them in the environment your client inherits (for example your shell profile), then start—or fully restart—the client so it picks them up; a client that was already running will not see newly exported values.
${env:VARIABLE}):
${VARIABLE}:
pmcp_live_... key directly instead.
How the agent should work
The gateway exposes three generic tools:search_operations, describe_operation, and execute_operation.
- Search the current allowed catalog.
- Describe the selected operation.
- Execute with the exact
policyRevisionandoperationRevisionthat description returned.
Troubleshooting
401: the key is invalid, expired, revoked, or not an MCP key.401withWWW-Authenticate: complete or renew the host’s OAuth link; do not substitute a legacy API key.429: respectRetry-Afterbefore retrying.scope_denied: add the smallest required permission in Pixie Settings, then retry with the same named key.
id when retrying the same tool call. Pixie stores a durable delegation claim keyed to that id and principal, returns a completed result for an identical replay, and rejects a conflicting request rather than running a second mutation.