> 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-cursor-and-others.md).

# Connect Cursor and other clients

Connect Cursor, VS Code, Windsurf, and your own agents to the Shortcut MCP server with an API token.

After this page, your editor or your own agent can use the Shortcut tools: look up customers, read the schedule, and, if the token allows, create leads and book jobs. Every client here connects the same way: the server's URL and a token in the `Authorization` header.

```
https://api.shortcutco.com/mcp
```

For a workspace on Shortcut's dev environment, use `https://dev.shortcutco.com/api/mcp` in every example below; see [Environments](/developers/concepts/conventions.md#environments).

Create a token for each client in **Settings → API & integrations**, as in [Connect Claude](/developers/mcp/connect-claude.md). Start with **Read everything**, and keep the token in an environment variable rather than in a file you might commit. The examples read it from `SHORTCUT_TOKEN`:

```bash
export SHORTCUT_TOKEN="scut_live_paste_your_token_here"
```

## Cursor

Add the server to `~/.cursor/mcp.json` for every project, or to `.cursor/mcp.json` in one project:

```json
{
  "mcpServers": {
    "shortcut": {
      "url": "https://api.shortcutco.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SHORTCUT_TOKEN}" }
    }
  }
}
```

Cursor reads `${env:SHORTCUT_TOKEN}` from the environment it was started in, so set the variable in your shell profile and restart Cursor. Open **Cursor Settings → MCP**: `shortcut` shows its tools once it connects. Cursor's guide: [Model Context Protocol](https://cursor.com/docs/context/mcp).

## VS Code

GitHub Copilot's agent mode reads `.vscode/mcp.json` in a workspace, or your user configuration (**MCP: Open User Configuration** in the Command Palette). An input prompts for the token once and VS Code stores it securely:

```json
{
  "inputs": [
    { "type": "promptString", "id": "shortcut-token", "description": "Shortcut API token", "password": true }
  ],
  "servers": {
    "shortcut": {
      "type": "http",
      "url": "https://api.shortcutco.com/mcp",
      "headers": { "Authorization": "Bearer ${input:shortcut-token}" }
    }
  }
}
```

Start the server from the file's **Start** link or with **MCP: List Servers**, then pick the Shortcut tools in the agent's tool picker. VS Code's guide: [MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).

## Windsurf

Open Cascade's MCP settings, choose to edit the raw configuration, and add:

```json
{
  "mcpServers": {
    "shortcut": {
      "serverUrl": "https://api.shortcutco.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SHORTCUT_TOKEN}" }
    }
  }
}
```

Refresh the server list after saving. Windsurf's guide: [MCP in Cascade](https://docs.devin.ai/desktop/cascade/mcp).

## Your own agent

### MCP TypeScript SDK

```ts
// agent.mjs: Node 18 or later. npm install @modelcontextprotocol/sdk
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(new URL("https://api.shortcutco.com/mcp"), {
  requestInit: { headers: { Authorization: `Bearer ${process.env.SHORTCUT_TOKEN}` } },
});
const client = new Client({ name: "my-shortcut-agent", version: "1.0.0" });
await client.connect(transport);

const { tools } = await client.listTools();
console.log(tools.map((tool) => tool.name));

const schedule = await client.callTool({ name: "get_schedule", arguments: {} });
console.log(JSON.stringify(schedule.structuredContent, null, 2));
await client.close();
```

### Claude API

The Messages API connects to remote MCP servers itself. Put the token in the server entry's authorization token field; Claude sends it as the bearer token:

```bash
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "mcp_servers": [
      { "type": "url", "url": "https://api.shortcutco.com/mcp", "name": "shortcut", "authorization_token": "'"$SHORTCUT_TOKEN"'" }
    ],
    "tools": [{ "type": "mcp_toolset", "mcp_server_name": "shortcut" }],
    "messages": [{ "role": "user", "content": "What is on the schedule today, by crew?" }]
  }'
```

Anthropic's guide: [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector).

### OpenAI Agents SDK

```python
# agent.py: pip install openai-agents
import asyncio, os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="shortcut",
        params={
            "url": "https://api.shortcutco.com/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['SHORTCUT_TOKEN']}"},
        },
    ) as shortcut:
        agent = Agent(name="Dispatcher", instructions="Answer questions about the Shortcut schedule.", mcp_servers=[shortcut])
        result = await Runner.run(agent, "What is on the schedule today, by crew?")
        print(result.final_output)

asyncio.run(main())
```

OpenAI's guide: [MCP in the Agents SDK](https://openai.github.io/openai-agents-python/mcp/).

## Plain HTTP

The server keeps no session, so any HTTP client can call a tool in one request. See [MCP overview](/developers/mcp/overview.md#protocol-details) for the headers and a `curl` example.

## Troubleshooting

* **No tools, or `401`.** The header must be `Bearer` , one space, then the whole token. Check the variable is set in the environment the client was started from.
* **A tool is missing.** The token lacks its scope. Ask the agent to call `explain_scopes`.
* **`403` "Requests from this origin are not allowed."** The server accepts browser requests only from Claude's web apps. Run your client from a server, a desktop app, or a script, which send no `Origin` header.