---
updatedAt: 2026-09-10T18:52:05.000Z
agentTools:
  projectIndex: https://developers.7shifts.com/llms.txt
---

# MCP Server

Our MCP server gives your AI assistant a live connection to the 7shifts API spec and documentation. Instead of guessing at endpoint names and field types, your assistant reads the real thing and can make real read requests against your account.

**Server URL:** `https://developers.7shifts.com/mcp`

It's public. You don't need credentials to connect, browse endpoints, or search our documentation. You only need an access token if you want your assistant to read live data.

<Callout icon="📘" theme="info">
  ### **Read-only.** The MCP server exposes `GET` endpoints only. `POST`, `PUT`, `PATCH`, and `DELETE` are not available. See [Why read-only](#why-read-only) below.
</Callout>

## Connect

### Claude Code

```bash
claude mcp add --transport http 7shifts https://developers.7shifts.com/mcp
```

### Cursor

**Settings → MCP → Add new MCP server**, or add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "7shifts": {
      "url": "https://developers.7shifts.com/mcp"
    }
  }
}
```

### VS Code (GitHub Copilot)

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "7shifts": {
      "type": "http",
      "url": "https://developers.7shifts.com/mcp"
    }
  }
}
```

### Claude (web and desktop)

**Settings → Connectors → Add custom connector**, then paste the server URL.

You don't need to be a developer to use this. If you want to explore what the API can do, check whether a workflow is possible, or draft a spec before handing it to engineering, this is a good way to do it without writing code.

## What your assistant can do

**API spec tools**

| Tool              | What it does                                            |
| ----------------- | ------------------------------------------------------- |
| `list-endpoints`  | Every path and method with a summary                    |
| `get-endpoint`    | Full detail on one endpoint — parameters, schemas, auth |
| `search-specs`    | Search across paths, operations, and schemas            |
| `list-specs`      | List our available API specs                            |
| `execute-request` | Make a live `GET` request against your account          |

**Documentation tools**

| Tool     | What it does                       |
| -------- | ---------------------------------- |
| `search` | Full-text search across our guides |
| `fetch`  | Retrieve a full guide page         |

With documentation search enabled, your assistant can read our integration guides such as the sales integration flow, employee sync, schedule enforcement and not just the endpoint list. That's the difference between an assistant that knows our endpoints and one that knows how our integrations are meant to be built.

## Enabling live reads

To let your assistant read data from your account, add your access token to the MCP config. It's forwarded on `execute-request` calls.

```json
{
  "mcpServers": {
    "7shifts": {
      "url": "https://developers.7shifts.com/mcp",
      "headers": {
        "Authorization": "Bearer {ACCESS_TOKEN}",
        "x-api-version": "2026-01-01"
      }
    }
  }
}
```

Create an access token under **Company Settings → Developer Tools**. See [Authentication](https://developers.7shifts.com/docs/authentication).

<Callout icon="❗️" theme="error">
  ### **Your token reads real employee data.**

  Nothing can be modified or deleted through MCP, but an access token is admin-level and there is no sandbox. Your assistant can read live wage data, employee records, and time punches for your company, and that data enters your AI tool's context.

  Consider whether that's appropriate for your account and your AI provider's data handling before adding a token. The spec and documentation tools work fine without one.
</Callout>

Two practical notes:

* **Set&#x20;**`x-api-version`**&#x20;explicitly.** Otherwise requests use whatever version your token defaults to, which may not match the spec your assistant is reading. See [Versioning](https://developers.7shifts.com/reference/versioning).
* **Don't commit your config.** Add `.cursor/mcp.json` and `.vscode/mcp.json` to `.gitignore`. A leaked access token is admin access to your company.

### Partners using OAuth

`execute-request` forwards static headers, so it doesn't suit the OAuth flow well. OAuth tokens expire after an hour and require an `x-company-guid` header alongside the bearer token, which means re-pasting a fresh token into your config every hour.

The spec and documentation tools work normally without any configuration, and are the more useful part for most partner work. If you do want live reads, use an access token from your development account rather than wiring OAuth into your MCP config.

## Why read-only

We've deliberately limited `execute-request` to `GET` endpoints.

Write operations against 7shifts aren't reversible in any meaningful sense. A deleted time punch, a published schedule, or a modified wage record affects real staff and real payroll, and there's no undo. An AI agent chooses its calls in the moment, sometimes mid-exploration, and the gap between "show me this week's punches" and "clean up the bad ones" is a single sentence.

You can still build integrations that write. The difference is that the code gets written, reviewed, and run by you rather than executed live by an agent mid-conversation:

```
Read the POST /v2/time_punches schema and write a Python function
that creates a punch. Don't try to call it — I'll run it myself.
```

Your assistant has full access to the request and response schemas for every endpoint, including write endpoints. Only live execution of them is blocked.

If read-only turns out to be the wrong call for your workflow, tell us in [Discussions](https://developers.7shifts.com/discuss).

## Try it

Once connected, ask your assistant things like:

**Understand the API**

```
Using the 7shifts MCP tools, explain how time punches relate to
shifts and users. Which endpoints do I need to read a week of
punch data for one location?
```

**Build something**

```
Write a Python script that pulls yesterday's time punches for
location 123 and flags any punch longer than 12 hours.
Use API version 2026-01-01.
```

**Check before you build**

```
I need to sync employees from our HR system into 7shifts.
Search the 7shifts docs for the employee sync guide and tell me
what the recommended approach is, and what happens to employees
who are deactivated on our side.
```

**Look at your real data**

```
Call GET /v2/companies, then pull the locations for my company
and show me them as a table.
```

## Rate limits

10 requests per second per IP address. If your assistant is looping through endpoints or retrying failures it can hit this quickly so tell it to add a rate limit backoff.

## Troubleshooting

**The assistant suggests OAuth when I have an access token.** Tell it explicitly: `"I'm using an access token, not OAuth. Don't include the x-company-guid header."`

**Requests fail with an unexpected schema.** Version mismatch. Set `x-api-version` in your MCP config and mention the version in your prompt.

**My assistant tried a POST or DELETE and it failed.** Expected — MCP is read-only. Ask it to generate the code instead and run it yourself.

`execute-request`**&#x20;returns 401.** Check the token is in the `headers` block of your MCP config, and that the technical contact on the token is still an active company admin. See [Authentication](https://developers.7shifts.com/reference/authentication).

**The assistant can't find a guide.** Documentation search covers guides and reference pages. Give it the URL directly — every page works with `.md` appended.

## Feedback

MCP support here is new. If your assistant consistently gets something wrong about our API, tell us in [Discussions](https://developers.7shifts.com/discuss) — it usually means our spec or docs need fixing, which helps every developer.