Skip to main content
Use REST for server-to-server reads. Use the traxy MCP connection when Claude or Codex should work with workspace data and confirmed actions.

Create an API key

Make a REST request and retrieve your first lead.

Connect Claude

Authorize Claude with OAuth.

Connect Codex

Authorize ChatGPT or Codex with OAuth.

​
REST base URL

Send an API key as a bearer token:
Do not send a workspace ID. traxy resolves the workspace from the credential.

​
Get one lead

Lead list responses put records in data and pagination state in page.

​
REST scopes

Default keys include these read scopes:
  • leads:read
  • analytics:read
  • icp:read
  • watchlist:read
  • content:read
  • integrations:read
  • sync:read
  • agent:read
  • workspace:read
Optional permissions include:
  • leads:contact_read
  • leads:contact_enrich
  • leads:manage
  • watchlist:manage
  • integrations:manage
  • integrations:deliver
  • agent:run
  • audience_analytics:read
  • audience_analytics:request
  • post_qualification:manage
The REST surface is read-first. Request-capable permissions protect the corresponding MCP tools. Contact enrichment also requires leads:read and leads:contact_read. Lead delivery also requires leads:contact_read.

​
Pagination

Cursor-based lists default to 50 items and accept at most 100.
  1. Send the first request without cursor.
  2. Read page.nextCursor.
  3. Pass that value unchanged in the next request.
  4. Keep every filter and sort setting the same.
  5. Stop when page.nextCursor is null.
Do not decode or construct cursors. A malformed or sort-incompatible cursor returns 400 validation_failed. traxy_list_agent_candidates is the exception. It uses limit and offset.

​
Lead results

GET /customer/leads returns active leads by default. Use disposition when you want another lead view. Useful filters include:
  • ICP match range
  • lead tier
  • lead state
  • Agent or Watchlist origin
  • monitored profile
  • LinkedIn post
  • engagement type
  • owner
  • company
  • text query
  • date range
Use GET /customer/leads/signals when you need the engagement, monitored profile, and post context behind the lead. Contact fields and LinkedIn profile URLs require leads:contact_read.

​
MCP connection

The MCP endpoint is:
Claude and Codex complete OAuth in the browser. The client negotiates the protocol version. traxy supports 2025-11-25 and 2025-06-18. The default OAuth grant adds leads:contact_read to the standard read scopes. An owner or admin must approve that access. A request containing only non-sensitive read scopes can be approved by any active workspace member. tools/list returns only the tools allowed by the approved scopes and current workspace access.

​
MCP tools

The current catalog has 42 scope-gated tools.

​
Connection and workspace

  • traxy_get_mcp_connection_status
  • traxy_get_workspace_access

​
Leads and accounts

  • traxy_list_leads
  • traxy_get_lead_counts
  • traxy_get_lead_stats
  • traxy_get_lead
  • traxy_enrich_lead_contact
  • traxy_list_lead_engagements
  • traxy_list_lead_signals
  • traxy_apply_lead_action
  • traxy_list_account_reports
  • traxy_get_account_report
traxy_apply_lead_action supports snooze, done, good, bad, and client. The done action requires the user to confirm and the call to include confirmDone: true.

​
Agent

  • traxy_get_agent_status
  • traxy_get_agent_budget_status
  • traxy_start_agent_run
  • traxy_list_agent_runs
  • traxy_list_agent_candidates
Starting a run requires confirmCreditSpend: true. The client should ask before it makes the call.

​
ICP and Watchlist

  • traxy_get_active_icp
  • traxy_list_watchlist_profiles
  • traxy_get_watchlist_profile
  • traxy_get_watchlist_summary
  • traxy_list_watchlist_recommendations
  • traxy_add_watchlist_profile
  • traxy_update_watchlist_profile
  • traxy_remove_watchlist_profile
  • traxy_restore_watchlist_profile
Watchlist management supports teammate, competitor, influencer, investor, and custom relationships. A custom relationship requires its label.

​
Content and analytics

  • traxy_get_analytics_dashboard
  • traxy_list_analytics_posts
  • traxy_get_post_summary
  • traxy_list_post_qualified_leads
  • traxy_list_content_feed

​
Integrations and sync

  • traxy_get_integrations_status
  • traxy_get_lead_delivery_state
  • traxy_create_webhook_destination
  • traxy_set_webhook_destination_enabled
  • traxy_deliver_lead_to_webhook_destination
  • traxy_get_sync_status
  • traxy_get_latest_qualification_run
Webhook-style destination tools support Webhook, Clay, n8n, and Zapier. Delivery requires the user to select the lead and destination.

​
Audience and post qualification

  • traxy_get_audience_post
  • traxy_find_audience
  • traxy_qualify_linkedin_post
  • traxy_get_organization_audience
Audience reads return aggregate analytics. Audience discovery and post qualification can start work that uses credits. Post qualification requires confirmCreditSpend: true.

​
MCP result filters

List tools use the same business filters as their REST counterparts where applicable.
  • Lead tools accept ICP range, state, origin, monitored profile, post, engagement, owner, company, query, and date filters.
  • Watchlist tools accept relationship, source, state, query, and sorting.
  • Post tools accept monitored profile, relationship, source, date, ICP, qualification status, query, and sorting.
  • Account reports accept company, ICP range, date, query, and aggregate sorting.
Use the tool schema returned by tools/list as the exact contract for the active grant.

​
Errors

REST errors use this envelope:
Common status codes:
  • 400 for invalid input
  • 401 for invalid, expired, or revoked credentials
  • 402 for insufficient credits or access
  • 404 when the requested resource is not available to the workspace
  • 429 for rate limits
Valid JSON-RPC requests use JSON-RPC errors for unknown methods, unknown tools, malformed calls, or missing scopes. A known tool with invalid arguments returns isError: true. Read structuredContent.error.issues, fix the named argument paths, and retry.

​
Data safety

  • Store API keys and OAuth tokens as secrets.
  • Do not send credentials in query parameters.
  • Grant contact access only when the workflow needs it.
  • Ask before any tool spends credits or changes workspace data.
  • Revoke keys and disconnect clients that are no longer used.