Connecting AI Agents with the MCP Server

Connect Claude, Codex, Cursor or any MCP-capable client to your Manage Roster workspace, and ask it questions in plain language:

Who is on leave next week?Which slots are empty this week?Which OT slots are still uncovered?Who hasn't submitted their work reports?

What this does

Manage Roster ships an MCP (Model Context Protocol) server at /mcp. It exposes your roster — agents, schedule, leave, holidays, overtime and work reports — as a set of tools an AI agent can call on your behalf.

The connection is scoped to one workspace and to the scopes you grant it. A read-only connection cannot change anything, and is not even shown the tools that would.

Why use it

• Ask instead of navigate. "Is next weekend covered?" is faster than opening the schedule and reading 48 cells.
• Cross-referencing is free. Coverage gaps, leave and holidays live on different pages in the app. A model can join them in one answer.
• It works where you already are. Your editor, your terminal, your Claude desktop app — no extra tab.

Requirements

• A Manage Roster account with access to at least one workspace
• An MCP-capable client (Claude Code, Claude Desktop, Codex, Cursor, or any client speaking streamable HTTP)
• API access enabled for the workspace (it is on by default; the owner can switch it off)

The endpoint URLs

Purpose	URL
MCP server	https://app.manageroster.com/mcp
REST API	https://app.manageroster.com/api/v1
Server info (unauthenticated probe)	GET https://app.manageroster.com/mcp

How to connect a client

Step 1 — Create a connection token

1. Open Settings → API & MCP in the app
2. Click Create token
3. Give it a name you will recognise later — the client it is for, usually (Claude Code — laptop)
4. Choose Read-only or Read and write
5. Tick the scopes it needs. See Connection scopes for what each one covers
6. Click Create

The token is shown once. Copy it now — it is stored hashed and cannot be retrieved again. If you lose it, revoke it and create another.

Step 2 — Add it to your client

Claude Code

claude mcp add manageroster \
  --transport http https://app.manageroster.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Codex

codex mcp add manageroster \
  --url https://app.manageroster.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Claude Desktop / Cursor — add to your MCP config file:

{
  "mcpServers": {
    "manageroster": {
      "type": "http",
      "url": "https://app.manageroster.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

The settings page generates all three snippets with your token already filled in, so you can copy rather than assemble them.

Step 3 — Confirm it works

Ask your agent:

Call get_workspace_info and tell me how many agents we have.

If it returns your workspace name and agent count, you are connected.

Read-only vs read and write

Read-only connections can query everything their scopes allow and change nothing. The write tools are not advertised at all, so the model never tries them and never wastes a turn discovering the wall.

Read and write connections can additionally assign and unassign shifts, file leave requests, and approve or reject leave.

Start read-only. Move to read and write once you know what you are going to use it for. The server instructs models to confirm with you before any write, but that is guidance to the model — the scope is the actual control.

WARNING

A token can never do more than the person who created it. If your workspace role is Member, you cannot mint a token that writes the schedule, even by editing the request by hand.

Managing the connection

From Settings → API & MCP you can:

• Edit scopes without rotating the token — your pasted config keeps working
• Toggle read-only on an existing token, which takes effect on the very next call
• Revoke a token, which stops it immediately
• See last used time and IP for every token, so a forgotten one is easy to spot

The AI activity log

Every call is recorded. Workspace owners and admins see the full log at Admin → API Activity:

• Who called, with which token, and from which IP
• Which tool or endpoint, and the parameters (free text such as leave reasons is redacted)
• Whether it was a read or a write
• Status and duration

This is the answer to "who enabled API access, and what did they actually do with it".

Security notes

• Tokens are stored hashed. The plaintext is shown once at creation and never again.
• Prefer the Authorization header over putting the token in a URL, so it cannot leak into proxy or server logs.
• Tokens are bound to one workspace. A token for Workspace A cannot see Workspace B, even if you belong to both.
• Removing someone from a workspace kills their tokens for it on the next call.
• Workspace owners have a kill switch that disables all API and MCP access at once.
• Revoke tokens for devices you no longer use. A token has no expiry unless you set one.

Troubleshooting

401 Unauthorized — the token is missing, mistyped, revoked or expired. Check the Authorization header reads Bearer <token> with a single space.

403 with "API access is disabled for this workspace" — the owner has used the kill switch. Re-enable it in Settings → API & MCP.

403 with "no longer a member of the workspace" — the user behind the token was removed from the workspace. Create a token from an account that is still a member.

A tool you expected is missing from tools/list — either the token lacks that tool's scope, or the token is read-only and the tool writes. Both are visible on the token's row in Settings.

"This connection is read-only" on a write tool — expected. Switch the token to read and write, or create a second token for the job.

The agent invents agent names or dates — tell it to call list_agents first, and to pass period (this_week, next_week) rather than computing dates. The server resolves those in your workspace timezone.

FAQ

Does this cost anything? No. API and MCP access is included with your workspace.

Can I connect more than one client? Yes, and you should use a separate token per client. That way the activity log tells you which machine did what, and losing one device means revoking one token.

Can an AI agent delete my schedule? It can unassign shifts if you granted schedule:write. There is no bulk-delete tool, and no tool that removes agents, workspaces or historical data. A read-only token cannot change anything at all.

Does the model see my data even when I do not ask about the roster? No. Tools run only when the model calls them, and every call is logged. It cannot read your workspace in the background.

What happens when I change a token's scopes? The change applies to the next call. The token itself does not change, so you do not need to update your client config.

Is there an OAuth flow? Not yet — v1 is bearer tokens. OAuth 2.1 with dynamic client registration is on the roadmap.

Related

• MCP tool reference — every tool and its arguments
• Connection scopes — what each scope permits
• REST API reference — the same data over plain HTTP