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 workspace — schedule, leave, holidays, overtime, work reports, agents and team members, support tickets, your notepad and workspace modules — as a set of tools an AI agent can call on your behalf.

The connection is scoped to one workspace, to the scopes you grant it, and to your role. It can do what you can do in the dashboard and nothing more. 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

Open API & MCP in the app. Agents find it in the sidebar; the owner, leads and managers find it under Tools → API & MCP
Click Create token
Give it a name you will recognise later — the client it is for, usually (Claude Code — laptop)
Choose Read-only or Read and write
Tick the scopes it needs. See Connection scopes for what each one covers
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

bash

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

Codex

bash

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

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

json

{
  "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 make changes, but only the changes your role can make in the dashboard. For example:

Owner, leads and managers can assign roster hours, run OT events, approve leave, manage holidays, agents, team members and work report templates, open support tickets and turn modules on or off. Some actions follow rank: leads can manage managers and agents, managers can manage agents, and only the owner and leads can silence missed work reports.
Agents can request and cancel their own leave, submit their own OT availability and work reports, and update their own notepad.

The What your token can do panel on the API & MCP page lists exactly what your role allows. The whoami tool returns the same list for a connected token.

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. Every call is checked against your current role, and agents are only offered the scopes their role can use. If your role changes, your tokens follow it on the very next call; after a promotion, tick any newly useful scopes on the token. See Scopes agents are offered.

Managing the connection

From Settings → API & MCP you can:

See what your token can do: a list of what your role is allowed to do through MCP and the API in this workspace
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

Who sees and manages which tokens:

Role	Sees	Can edit or revoke
Owner	Every token in the workspace, plus recent API activity	Every token
Lead	Every token in the workspace, plus recent API activity	Their own, and those of managers and agents (not the owner's)
Manager, Agent	Only their own tokens	Only their own

The AI activity log

Every call is recorded. The owner opens the full log from Settings → API Activity, and the owner and leads also see the latest calls at the bottom of the API & MCP page:

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.
Tokens don't expire on their own. Revoke tokens for devices you no longer use.

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 — the token lacks that tool's scope, the token is read-only and the tool writes, or the tool is for a role you don't have (for example, team and template tools are for the owner, leads and managers, and silencing missed reports is for the owner and leads). Scopes and read-only are visible on the token's row; your role's list is in What your token can do.

feature_unavailable — the module behind that tool (Overtime, Leave Management, Holiday Calendar or Work Reports) is turned off for the workspace, or the owner's plan doesn't include it. The tool stays listed but refuses until a manager, lead or the owner turns the module on in Modules.

"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 (or list_team) first, and, where a tool accepts it, 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 or data? Only what your role could delete in the dashboard, and only with a write scope. It can unassign roster hours with schedule:write. Tools that would delete history, such as deleting an agent (delete_agent), removing a team member who has a roster agent (remove_team_member) or deleting a report template that has submissions (delete_report_template), refuse until the call explicitly confirms. The refusal says exactly what would be deleted, so the model has to show you before going ahead. There is no tool that deletes a workspace. 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.

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

Connecting AI Agents with the MCP Server ​

What this does ​

Why use it ​

Requirements ​

The endpoint URLs ​

How to connect a client ​

Step 1 — Create a connection token ​

Step 2 — Add it to your client ​

Step 3 — Confirm it works ​

Read-only vs read and write ​

Managing the connection ​

The AI activity log ​

Security notes ​

Troubleshooting ​

FAQ ​

Related ​