MCP for agents

YardPilot can expose the same tools as the HTTP catalog to an MCP client such as Claude, Cursor, Codex, or Grok. There is no in-app chat.

Integration API keys (ypk_live_… / ypk_test_…) are not MCP keys. Do not put them in a Bearer header.

Staff agents (browser sign-in)

Grok, Claude Code, Codex, and Cursor take a URL and open a browser. They do not have a place to paste a Bearer token.

1. In the app, open Settings → API Keys.
2. In MCP for agents, copy the Staff URL (/mcp/crm on the host you are signed in on).
3. Add that URL in the client. When it asks you to authenticate, sign in to YardPilot and click Approve.

Tools then run as your staff user. Change crm to another staff profile if you need a smaller or larger tool set.

Company robots (header token)

CI and other clients that send Authorization: Bearer use a company ypm_ token on /mcp/tenant/{profile}.

1. In Settings → API Keys → MCP for agents, copy the Robot URL.
2. Click Generate MCP token.
3. Copy the ypm_ secret immediately. YardPilot shows it once.

{
  "mcpServers": {
    "yardpilot-crm": {
      "url": "https://app.yardpilot.io/mcp/tenant/crm",
      "headers": {
        "Authorization": "Bearer <ypm_token>"
      }
    }
  }
}

That token is hashed, scoped to your company, and cannot call platform admin profiles. Do not commit tokens.

The staff URL is an MCP server, not a webpage. Opening it in a browser shows how to connect. Sign-in starts from the MCP client, not from that page.

Profiles

Pick the smallest profile that covers the job. Company tokens can use staff profiles only:

Profile	Examples
field-day	Today's visits, get visit, complete visit
crm	Contacts and properties
operations	Jobs and visits
commercial	Quotes, invoices, payments, refunds
communications	Campaigns, templates, email and SMS
workforce	Users, teams, leave, attendance, roster
foundation	Company profile, catalog, checklists, notes
staff-full	Union of the staff profiles

admin-read and admin-ops are platform-admin personal tokens only. A company ypm_ token is rejected there.

Staff personal tokens

A signed-in staff or platform-admin user can still mint a Sanctum personal access token and send it as Bearer on /mcp/{profile} if the client supports headers. Most agent UIs do not. Prefer the Staff URL plus browser above. Admin tokens use admin-read and admin-ops only.

The HTTP catalog at GET /capabilities is unchanged. Use that from the CLI. MCP is tools/list on the profile URL.