> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/mcp/connect-claude.md). # Connect Claude Connect Claude.ai, Cowork, Claude Desktop, Claude Code, or the Claude API to your Shortcut workspace by signing in, or with an API token. After this page, Claude can look up your customers, read your schedule, and, if you allow it, create leads in your Shortcut workspace. It takes a few minutes. The Shortcut MCP server is at: ``` https://api.shortcutco.com/mcp ``` Workspaces on Shortcut's dev environment use `https://dev.shortcutco.com/api/mcp`; see [Environments](/developers/concepts/conventions.md#environments). There are two ways to connect, and both need a company admin: * **Sign in** (recommended for Claude.ai, Cowork, Claude Desktop, and Claude Code). You sign in to Shortcut from Claude and approve read-only access. Nothing to copy or paste. * **API token.** You create a token in Shortcut and paste it into Claude as a request header. Use this when Claude needs to write, for example to create leads, or when your Claude organization can't use sign-in. ## Sign in from Claude ### Claude.ai, Cowork, and Claude Desktop 1. In Claude, open **Customize → Connectors** and select **Add custom connector**. On Team and Enterprise plans, an Owner adds it for everyone under **Organization settings → Connectors** (**Add**, then **Custom**), and each member then connects with their own Shortcut sign-in. 2. Name: `Shortcut`. Remote MCP server URL: `https://api.shortcutco.com/mcp`. Leave the OAuth client fields empty. 3. Select **Add**, then **Connect** on the Shortcut connector. 4. Claude opens Shortcut. Sign in with your Shortcut email and password if asked. 5. Shortcut shows what Claude is asking for: your workspace, where it sends you back (`claude.ai`), and the scopes. Sign-in asks for read access to everything the API covers. Select **Approve**. You're back in Claude, and the connector lists Shortcut's read tools. Only company admins can approve; anyone else sees "Ask a company admin". ### Claude Code ```bash claude mcp add --transport http --scope user shortcut https://api.shortcutco.com/mcp ``` Inside Claude Code, run `/mcp`, choose `shortcut`, and select **Authenticate**. Your browser opens Shortcut's sign-in and approval page. Because Claude Code receives the answer on your own computer (`localhost`), Shortcut warns you to approve only a connection you just started. ### What sign-in grants * Read access to customers, leads, estimates, jobs, visits, invoices, payments, services, products, tags, custom fields, crews, and staff. Claude acts as the admin who approved it. * Claude stays connected: it refreshes its access on its own, about once an hour, for as long as the connection is used. A connection unused for 30 days has to sign in again. * The connection ends when you disconnect it in **Settings → API & integrations → Connected apps**, when the admin who approved it is deactivated or is no longer a company admin, or when the connection's credentials are used in a way that suggests they were copied. For writes such as creating leads, use an API token with exactly the scopes you want. ## Connect with an API token Claude sends the token in the `Authorization` header. A company admin creates the token; whatever scopes the token has are everything Claude can do. ### 1. Create a token for Claude 1. In Shortcut, open **Settings → API & integrations** and select **Create token**. 2. Name it after the connection, for example `Claude`. 3. Choose scopes. Start read-only: choose **Read everything**, or **Custom** with **Read customers**, **Read visits**, and **Read crews**, plus **Read invoices** and **Read payments** for billing questions. Add **Write leads** only if you want Claude to create leads. A lead Claude creates behaves like one from your website form: staff are notified. Without **Trigger automations**, records Claude creates or changes start none of your **Automations** rules or the new-lead welcome automation. 4. Select **Create**, then **Copy**. Shortcut shows the token once. Give Claude its own token rather than reusing an integration's, so you can revoke one without breaking the other. Do not give an unsupervised agent **Complete visits**, **Write payments**, **Trigger automations**, or a **Send** scope: those create invoices, move money, or message your customers. ### 2. Connect your Claude app Each Claude app below sends the token in the `Authorization` header. #### Claude Code Put your token in your shell as `SHORTCUT_TOKEN`, then run this in a terminal. The single quotes keep `${SHORTCUT_TOKEN}` as written, so Claude Code reads the token from your environment each time instead of saving it in its configuration: ```bash claude mcp add --transport http --scope user shortcut https://api.shortcutco.com/mcp --header 'Authorization: Bearer ${SHORTCUT_TOKEN}' ``` Check the connection: ```bash claude mcp list ``` `shortcut` should show as connected. Inside Claude Code, `/mcp` lists its tools. `--scope user` makes Shortcut available in every project on this machine. Without it, Claude Code saves the server for the current project only. To share the server with a project's collaborators without sharing the token, use `--scope project` instead. Claude Code then writes `.mcp.json` in the project, with the header reading the token from `SHORTCUT_TOKEN`, so each person sets it in their own shell: ```json { "mcpServers": { "shortcut": { "type": "http", "url": "https://api.shortcutco.com/mcp", "headers": { "Authorization": "Bearer ${SHORTCUT_TOKEN}" } } } } ``` Never commit a token to a repository. #### Claude.ai and Cowork Claude.ai adds the Shortcut server as a custom connector with the token as a request header. Request-header authentication in Claude.ai is in beta and available to a limited set of organizations: when the **Add custom connector** dialog shows a **Request headers** section, Shortcut connects in a minute. When it does not, use Claude Code, Claude Desktop, or the Claude API below. Anthropic's guide: [Add a connector that isn't in the directory](https://claude.com/docs/connectors/custom/add-unlisted). On Free, Pro, and Max plans, you add the connector to your own account (Free allows one custom connector): 1. In Claude, open **Customize → Connectors** and select **Add custom connector**. 2. Enter the server URL: `https://api.shortcutco.com/mcp`. 3. For **Authentication**, choose **No sign-in**. 4. Under **Request headers**, choose `authorization` and enter `Bearer` followed by your token, including the space: `Bearer scut_live_k7Qm3pX2Lw9a_…`. Claude sends the value exactly as entered. 5. Select **Add**. Claude lists the Shortcut tools your token allows. On Team and Enterprise plans, an Owner adds the connector for everyone under **Organization settings → Connectors**: **Add**, then **Custom**, then the same URL, authentication, and request header. Members then find it under **Customize → Connectors** with the **Custom** label. Every member who uses the connector shares the Owner's token, so whatever it allows, each of them can do. Create a dedicated token for it with the fewest scopes the team needs, such as **Read everything**, and name it after the connector so you can revoke it on its own. In a chat, select **+**, then **Connectors**, and turn Shortcut on. Authentication settings, including the header, cannot be edited later: to change the token, remove the connector and add it again. #### Claude Desktop Claude Desktop shows the same connectors as Claude.ai, so a connector added there works in the desktop app too. To connect Claude Desktop directly instead, add the server to its configuration file through `mcp-remote`, which runs on your computer and sends the header for you (it needs Node.js). Open **Settings → Developer → Edit Config** and add: ```json { "mcpServers": { "shortcut": { "command": "npx", "args": ["-y", "mcp-remote", "https://api.shortcutco.com/mcp", "--header", "Authorization:${SHORTCUT_AUTH_HEADER}"], "env": { "SHORTCUT_AUTH_HEADER": "Bearer scut_live_paste_your_token_here" } } } } ``` Restart Claude Desktop; Shortcut appears in the chat's connectors. The header is passed through `env` because Claude Desktop splits arguments on spaces. `mcp-remote`'s guide: [README](https://github.com/geelen/mcp-remote#readme). #### Claude API The Messages API connects to the Shortcut server itself when you list it among the request's MCP servers. See [Connect Cursor and other clients](/developers/mcp/connect-cursor-and-others.md#claude-api). ## Try it Ask Claude things like: * "Find the customer at 412 Elm St and show me their properties." * "What's on the schedule today, by crew?" * "Which visits does the North crew have this week?" * "Add a lead: Robin Smith, , 412 Elm St, Bozeman, wants weekly mowing." (needs **Write leads**) * "What can you do in Shortcut with this connection?" ## Tools Claude sees only the tools the token's scopes allow. A read-only token shows a read-only toolset. | Tool | What it does | Scope it needs | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `find_customer` | Finds customers by name, company, email, phone, or address | Read customers | | `get_customer` | One customer with contact details, tags, and properties | Read customers | | `get_schedule` | Visits on the schedule for a day or date range, in schedule order: by date, then crew, then route position. Up to 50 visits a call, with a total for the whole range and, for each date and crew on the page, its own total | Read visits; crew names need Read crews, customer names need Read customers | | `list_visits` | Visits filtered by date, crew, status, customer, or job | Read visits | | `get_visit` | One visit with its crew, address, and times | Read visits | | `create_lead` | Creates a lead that behaves like one from your website form; its source in the app reads **API** | Write leads; Write customers when the email belongs to an existing customer; automations start only with Trigger automations | | `list_leads` | Leads filtered by status, stage, or source | Read leads | | `get_lead` | One lead with contact details, address, and what they asked for | Read leads | | `update_lead` | Changes a lead's contact details, address, hours estimate, or square footage | Write leads; Write customers when the change reaches a customer's records | | `dismiss_lead` | Sets a lead aside | Write leads | | `restore_lead` | Opens a dismissed lead again | Write leads | | `list_estimates` | Estimates filtered by status, customer, or lead | Read estimates | | `get_estimate` | One estimate with its lines and options | Read estimates | | `create_estimate` | Creates a draft estimate for a lead from catalog services; the app prices it and nothing is sent | Write estimates; Write customers when the lead's email belongs to an existing customer | | `update_estimate` | Changes a draft estimate's message, property, or lines | Write estimates | | `send_estimate` | Emails or texts the estimate to the customer, as Send does in the app | Send estimates and Read estimates | | `remind_estimate` | Reminds the customer about a pending estimate, at most once per estimate every ten minutes | Send estimates and Read estimates | | `approve_estimate` | Approves an estimate on the customer's behalf and creates its jobs, as approving in the app does | Write estimates; automations run only with Trigger automations | | `void_estimate` | Voids an estimate so it can no longer be approved | Write estimates | | `list_jobs` | Jobs filtered by customer, property, status, or crew | Read jobs | | `get_job` | One job with its price, cadence, crew, and next visit | Read jobs | | `list_job_visits` | One job's visits | Read jobs and Read visits | | `create_jobs` | Creates pending jobs from catalog services | Write jobs | | `schedule_job` | Puts a pending job on the schedule | Write jobs; automations start only with Trigger automations | | `update_job` | Changes a job's name, description, or crew | Write jobs | | `pause_job` | Pauses a scheduled job | Write jobs | | `resume_job` | Resumes a paused job from a date | Write jobs | | `cancel_job` | Cancels a job and its open visits | Write jobs | | `list_services` | The service catalog | Read services | | `get_service` | One service with its price | Read services | | `create_service` | Adds a service | Write services | | `update_service` | Changes a service | Write services | | `deactivate_service` | Stops offering a service | Write services | | `reactivate_service` | Offers a service again | Write services | | `list_products` | The products catalog | Read products | | `get_product` | One product | Read products | | `create_product` | Adds a product | Write products | | `update_product` | Changes, archives, or restores a product | Write products | | `list_teams` | Crews and their members | Read crews | | `get_team` | One crew and its members | Read crews | | `list_users` | Staff | Read staff | | `get_user` | One staff user | Read staff | | `list_invoices` | Invoices filtered by status, customer, or due date | Read invoices | | `get_invoice` | One invoice with its amounts, due date, and lines | Read invoices | | `list_payments` | Payments filtered by invoice or customer | Read payments | | `get_payment` | One payment with its method, reference, and amount refunded | Read payments | | `explain_scopes` | What this connection can and cannot do, and how to grant more | None | Dates are in your workspace's timezone. Lists return at most 50 items per call; Claude asks for the next page when it needs more. When Claude creates a lead or an estimate, sends, reminds, or approves, it can pass a `requestKey`, so a retried request never acts twice. If Claude says a tool needs a scope, a company admin creates a new token with that scope and replaces the one in the connector. Tokens cannot be changed after they are created. ## Revoke access * **Signed in:** in **Settings → API & integrations → Connected apps**, select **Disconnect** next to Claude. * **Token:** revoke the token in **Settings → API & integrations**. Either way, Claude loses access on its next request. Remove the connector in Claude too. ## Every Claude app With a token, Claude Code, Claude.ai, Cowork, Claude Desktop, and the Claude API all send it in the `Authorization` header, so a token connects any of them, and what that token allows is the same everywhere. A token connector an Owner adds for a Team or Enterprise organization shares one token across its members; a token in Claude Code or a desktop configuration is yours alone. Signing in creates one connection per Claude app you sign in from, each listed under **Connected apps**. See [MCP overview](/developers/mcp/overview.md) for how scopes shape the tools Claude sees. ## Troubleshooting * **Sign-in says "Ask a company admin".** Only company admins can approve a connection. Ask one to connect, or to create a token for you. * **Sign-in says Shortcut couldn't identify the app, or the app's return address isn't registered.** Remove the connector and add it again with the URL exactly as above. * **Claude shows no Shortcut tools, or the connection fails.** Check the header value starts with `Bearer` , then a space, then the whole token. A revoked or expired token fails the connection. * **A tool is missing.** The token lacks its scope. Ask Claude to call `explain_scopes` for the exact scope. * **"Requests from this origin are not allowed."** The server accepts connections from Claude's apps and from server-side clients. Browser-based tools on other sites cannot call it.