Skip to main content

Before you connect

Pixie MCP supports OAuth sign-in and scoped MCP keys. It is a separate, least-privilege integration from the REST API. Use https://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. Configure https://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.
  1. Ask your client to connect Pixie.
  2. Sign in to Pixie.
  3. Review the requesting app’s name, permissions, and return address.
  4. Choose Allow or Deny.
  5. Return to the client and verify access with a read-only operation such as leadFinder.sources.
Pixie binds every OAuth token to the exact MCP resource and checks expiry and scopes on every request. Consent does not launch Outbound or send messages.

Scoped MCP keys

Clients that use keys need a named key beginning with pmcp_live_. Do not use a legacy pk_live_ REST API key at this endpoint.
  1. In Pixie, open Settings → API.
  2. Create a named key and select only the permissions the client needs.
  3. Copy the key immediately. Pixie shows it once and never stores the raw value.
The external coding agent supplies its own model inference.

Configure an MCP client

Use this endpoint and bearer token in a supported remote-MCP configuration:
For example, a client configuration that accepts HTTP headers should use:
Store the value in the client’s secret store or environment, never in source control.

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 the Authorization: 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.
Interpolation syntax differs by client, so copy the block that matches yours—do not mix them. Cursor (and other clients that use ${env:VARIABLE}):
Clients that use bare ${VARIABLE}:
If your client does not support interpolation at all, paste the literal endpoint and pmcp_live_... key directly instead.

How the agent should work

The gateway exposes three generic tools: search_operations, describe_operation, and execute_operation.
  1. Search the current allowed catalog.
  2. Describe the selected operation.
  3. Execute with the exact policyRevision and operationRevision that description returned.
Lead Finder creation already starts or reuses its first Run. Poll that exact Run until it is terminal; never substitute a newer Run. Preparing Outbound creates or resumes a reviewable draft only—launch and send actions remain human-only in Pixie.

Troubleshooting

  • 401: the key is invalid, expired, revoked, or not an MCP key.
  • 401 with WWW-Authenticate: complete or renew the host’s OAuth link; do not substitute a legacy API key.
  • 429: respect Retry-After before retrying.
  • scope_denied: add the smallest required permission in Pixie Settings, then retry with the same named key.
Revoking a key or reducing its permissions takes effect on the next request. For retry-safe clients, retain the JSON-RPC request 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.