MCP access — Skopo docs

Skopo exposes a remote MCP (Model Context Protocol) endpoint at https://skopo.dev/api/mcp. Connect an AI assistant — such as Claude, Claude Code, or Codex — so it can read your projects, create and update work items, move workflow status through methodology gates, and add comments.

Most clients connect with sign-in and approve: you add the URL, the client opens Skopo in your browser, you approve, and you're done — there's no token to copy. Settings → MCP access shows the same steps for each client.

Connect with sign-in (recommended)

Claude (claude.ai and Claude Desktop)

Open Settings → Connectors and choose Add custom connector.
Name it Skopo and paste https://skopo.dev/api/mcp as the URL.
Click Connect, sign in to Skopo if asked, and click Approve.

Claude Code

claude mcp add --transport http --scope user skopo https://skopo.dev/api/mcp

Then start Claude Code, run /mcp, select skopo, and choose Authenticate. Approve in the browser tab that opens. --scope user makes Skopo available in every project; leave it out to add it to the current project only.

Codex

Add the server to ~/.codex/config.toml:

[mcp_servers.skopo]
url = "https://skopo.dev/api/mcp"

Then run codex mcp login skopo and approve in the browser tab that opens.

What you're approving

The approve screen shows the app's name, where you'll be sent back to, and what it can do. Skopo doesn't verify app names, so only approve a connection you just started yourself. Access lasts until you disconnect: open Settings → MCP access → Connected apps and click the disconnect icon next to the app.

Connect with a personal token (fallback)

Use a token only for clients that can't sign in with OAuth.

Open Settings → MCP access, and under Personal tokens give the token a name and click Create token.
Copy the token immediately — it's shown only once. Anyone with the token can access your Skopo data on your behalf, so keep it private and revoke it from the same list when you stop using it.
Send it as a Bearer token. The usual configuration shape is:

{
  "mcpServers": {
    "skopo": {
      "url": "https://skopo.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

To check any connection, ask your assistant to "list my Skopo projects".

For client developers

Skopo implements the MCP authorization spec: the endpoint answers unauthenticated requests with 401 and a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource/api/mcp. The authorization server metadata is at /.well-known/oauth-authorization-server, with dynamic client registration, the authorization code flow with PKCE (S256), refresh-token rotation, and token revocation. Access tokens last one hour; refresh tokens last 90 days.

Available tools

Once configured, your AI assistant can call the following tools:

Tool	What it does
`list_projects`	Returns all projects you have access to, including their `publicId`, name, key, and active methodology.
`get_project_methodology`	Returns the full methodology configuration for a project — workflow states, work-item types, and valid status transitions.
`list_members`	Lists the people and AI agents on a project. A person's `id` is the `assigneeId` for work items; an agent's `id` filters `list_agent_queue`.
`create_work_item`	Creates a new work item in a project.
`get_work_item`	Fetches a single work item by key or ID, including images embedded in its description and comments.
`get_attachment`	Returns one embedded image by its attachment ID or URL, for images that were too large to include in `get_work_item`.
`upload_attachment`	Uploads a PNG, JPEG, GIF, or WebP image sent as base64, such as a screenshot for evidence. Returns the image URL and a markdown snippet. Pass a work item `key` to append the image to the end of that item's description.
`list_work_items`	Lists work items in a project one page at a time, filtered by status, type, assignee, sprint, priority, blocked, text, or update time.
`get_board`	Returns the project board grouped by workflow state, with dashboard, backlog, and repositories. Set `compact` for just the columns.
`update_work_item`	Updates title, description, status, assignees, priority, start and due dates, points or labels.
`add_work_item_comment`	Adds a comment to a work item. Mention teammates with `@Full Name`.
`search_work_items`	Searches work items by text across every project you can access.
`bulk_update_work_items`	Applies the same change to several work items at once.
`list_sprints`	Lists a project's sprints with goal, dates, capacity, and state (`planned`, `active`, `completed`, or `unscheduled`).
`create_sprint` / `update_sprint`	Creates a sprint or edits its name, goal, dates, and capacity.
`start_sprint`	Starts a sprint today. Only one sprint can be active at a time.
`complete_sprint`	Completes the active sprint and moves unfinished items to another sprint or back to the backlog.
`list_goals`	Lists a project's goals and their progress.
`create_goal` / `update_goal`	Creates a goal, or updates its status (`draft`, `active`, `at_risk`, `achieved`), current value, target value, measure, or target date.
`list_risks` / `create_risk`	Reads or records project risks.
`update_risk`	Updates a risk's status (`open`, `monitoring`, `mitigated`, `closed`), probability, impact, or mitigation.
`list_decisions` / `create_decision` / `update_decision`	Reads, records, or updates decisions. Setting status `decided` records when it was decided.
`list_dependencies` / `create_dependency` / `update_dependency`	Reads, records, or updates dependencies between work items and projects. Targets must be in the same organization.
`list_releases`	Lists releases with the readiness gates and the risks, dependencies, and policy checks blocking them.
`create_release` / `update_release`	Creates a release, or changes its status or notes. `ready` and `released` are refused until every readiness gate passes.
`list_agent_queue`	Lists agent assignments waiting for work, with instructions and work item details.
`claim_agent_assignment`	Claims an approved assignment so the agent can start working on it.
`complete_agent_assignment`	Marks an assignment done with a summary and an optional result link, such as a pull request.
`block_agent_assignment`	Marks a claimed assignment blocked with a reason. Claim it again once the blocker is resolved.

Write tools require the scopes described below. The agent queue tools let Claude Code or Codex work through the assignments you give your AI agents on the Team page.

Keeping responses small

Each tool returns its data twice: as structuredContent and as a one-line summary followed by compact JSON in the text content, for clients that ignore structuredContent. To keep large projects cheap:

list_work_items returns one page (default 100 items, limit up to 500) with total and nextCursor. Pass nextCursor back as cursor to read the next page; null means you have everything.
compact: true on list_work_items or get_board returns only key, displayRef, title, status, statusLabel, workItemTypeKey, priority, points, assigneeId, blocked, and updatedAt per item. A compact board also leaves out the dashboard, backlog, and repositories and adds a count per column.
fields picks exactly the item fields you need, for example ["title", "status"]. key is always included.

Statuses and types

Statuses come from the project's methodology. status on list_work_items, create_work_item, update_work_item, and bulk_update_work_items accepts the state id (inprogress) or its label (In Progress, or Building in Shape Up), ignoring case. workItemTypeKey and type accept a type key or label the same way; type also still accepts the legacy feature, bug, issue, and epic. Work items in tool output carry both status (the id) and statusLabel. An unknown value is rejected with an error that lists the project's valid states or types.

Every tool carries MCP annotations: read tools (list_*, get_*, search_work_items) are marked read-only, so clients that support it can run them without asking each time, while update_work_item and bulk_update_work_items are marked as overwriting existing values. The server also sends instructions on connect that describe the normal flow, so assistants know to start with list_projects and get_project_methodology.

Creating a work item

To create a work item through your AI assistant, follow this flow:

Call list_projects to get the project publicId (a string like prj_S8qDRLbDJWbp).
If the target status or work-item type is unclear, call get_project_methodology first. This ensures the item matches the project's active methodology — for example, a Scrum project uses story or bug types and requires a status that exists in its configured workflow.
Call create_work_item with at minimum a projectId and title:

{
  "projectId": "prj_S8qDRLbDJWbp",
  "title": "Describe the work item",
  "status": "backlog"
}

Required fields: projectId, title.

Optional fields: status, type, workItemTypeKey, points, assigneeId, sprintId, parentIssueId.

To assign someone, call list_members and pass the person's id as assigneeId. Only people on the project can be assigned.

projectId accepts either the database UUID or the public ID (prj_...); prefer the public ID. The status and workItemTypeKey values are validated against the project methodology and accept either ids or labels — if you pass an invalid value, the request is rejected with an error listing the valid values. Use get_project_methodology to look up valid values before creating items.

Verify the result with get_work_item or list_work_items.

Managing sprints

Sprint tools work on projects whose methodology plans in sprints: Scrum, and Scrumban with the Sprint goals practice. Only project leads and workspace owners can create, edit, start, or complete sprints; other members can still call list_sprints.

Call list_sprints to get sprint ids and see which sprint is active.
Call create_sprint with projectId and name, plus optional goal, startDate and endDate (YYYY-MM-DD), and capacity in points. update_sprint takes the same fields and a sprintId; send null to clear one. Completed sprints cannot be edited.
Call start_sprint with the sprintId. The start date becomes today and the end date stays as planned, or follows the project's sprint length if it is missing. Pass endDate to override it. If another sprint is still active, complete it first.
Call complete_sprint with the sprintId and a rolloverSprintId. Done items stay with the sprint; unfinished items move to that sprint, or to the backlog when rolloverSprintId is null. The response lists completedItems and rolledOverItems by key.

Planning records

Goals, risks, decisions, dependencies, and releases use the same rules as the Delivery and Operations views:

Updates are partial. update_goal, update_risk, update_decision, update_dependency, and update_release take the record's id (from the matching list_ tool) and change only the fields you pass.
Dependencies need at least one of sourceWorkItemKey (a work item in this project), targetWorkItemKey, or targetProjectId. targetProjectId accepts a prj_... id and must be a project in the same organization that you can access. list_dependencies only expands linked work items and projects you can access. relationType is blocks (default), depends_on, or relates.
Release readiness has four gates: a goal is active or achieved, an artifact is approved, every policy check passes or has an active exception, and there are no open high-impact risks or unresolved dependencies. list_releases returns readiness.gates, the blocking records in readiness.blockers, and blockedBecause on each release. update_release refuses ready and released until every gate passes.
Risk, decision, and dependency changes emit the same metric events as edits in the app.

Uploading an image

Call upload_attachment with the project's publicId, a filename, a mimeType (image/png, image/jpeg, image/gif, or image/webp), and the file bytes as base64 in data. A data:image/png;base64,... URL is also accepted. Your workspace plan sets the largest file you can upload.

{
  "projectId": "prj_S8qDRLbDJWbp",
  "filename": "checkout-error.png",
  "mimeType": "image/png",
  "data": "iVBORw0KGgo...",
  "key": "BUG-12"
}

With key, the image is added as a new paragraph at the end of that work item's description. Without key, nothing else changes: put the returned markdown into a description with update_work_item, or into a comment with add_work_item_comment. The response includes the attachment's id, filename, mimeType, byteSize, and absolute url.

Scopes

Creating and updating work items and planning records (goals, risks, decisions, dependencies, releases), managing sprints, and uploading images with upload_attachment require the work_items:write scope. Observers can't upload images. Read-only operations (list_projects, get_project_methodology, list_members, list_work_items, get_work_item, get_attachment, list_sprints, and the list_ tools for planning records) require only work_items:read. Apps that sign in with OAuth can request a subset of these scopes, and the approve screen lists exactly what each app gets.