MCP Integration

The Umaku MCP server lets AI IDEs like Cursor, Windsurf, Kiro, and VS Code — as well as AI assistants like Claude and ChatGPT — talk directly to your Umaku workspace. You can query projects, manage sprints, move tasks, report bugs, and more — all from your editor’s AI chat.

How it works

AI IDE  --MCP-->  Umaku MCP Server  --HTTP-->  Umaku Backend
        token                        Bearer

Your MCP token is passed from the IDE to the server, which forwards it as a Bearer token to the Umaku backend. All operations respect your account’s RBAC permissions.

Get your MCP token

Go to Account Settings → MCP in the Umaku platform and generate a personal token. It looks like mcp_xxxxxxxxxxxxxxxx.

Setup

The MCP server is already running at https://mcp.umaku.ai/mcp. Just add the config below to your IDE — no installation needed.

{
  "mcpServers": {
    "umaku": {
      "type": "http",
      "url": "https://mcp.umaku.ai/mcp",
      "headers": {
        "x-umaku-token": "mcp_your_token_here"
      }
    }
  }
}

{
  "mcpServers": {
    "umaku": {
      "type": "http",
      "url": "https://mcp.umaku.ai/mcp",
      "headers": {
        "x-umaku-token": "mcp_your_token_here"
      }
    }
  }
}

{
  "mcpServers": {
    "umaku": {
      "type": "http",
      "url": "https://mcp.umaku.ai/mcp",
      "headers": {
        "x-umaku-token": "mcp_your_token_here"
      }
    }
  }
}

VS Code supports MCP servers via the GitHub Copilot extension (VS Code 1.99+).

Add this to your .vscode/mcp.json (workspace) or user settings.json:

{
  "servers": {
    "umaku": {
      "type": "http",
      "url": "https://mcp.umaku.ai/mcp",
      "headers": {
        "x-umaku-token": "mcp_your_token_here"
      }
    }
  }
}

Or via settings.json:

{
  "mcp": {
    "servers": {
      "umaku": {
        "type": "http",
        "url": "https://mcp.umaku.ai/mcp",
        "headers": {
          "x-umaku-token": "mcp_your_token_here"
        }
      }
    }
  }
}

Claude supports MCP connectors via the Connectors settings page.

Go to claude.ai → Settings → Connectors
Click Add custom connector
Fill in the fields:
- Name: Umaku
- Remote MCP server URL: https://mcp.umaku.ai/mcp?token=mcp_your_token_here
Leave OAuth Client ID and OAuth Client Secret empty
Click Add

ChatGPT supports MCP connectors for Plus, Pro, and Team users.

Go to chatgpt.com → Settings → Connectors (or look for MCP under tools)
Click Add connector or Add MCP server
Fill in the fields:
- Name: Umaku
- URL: https://mcp.umaku.ai/mcp?token=mcp_your_token_here
Click Add

Verify the connection

Once configured, ask your AI assistant:

“Call health_check”

A successful response confirms your token is valid and shows your user profile.

Available tools

Health

Tool	Description
`health_check`	Verify connectivity and confirm which user you are acting as

Organizations

Tool	Description
`organizations_list`	List all organizations you belong to
`organizations_get`	Get full details of an organization

Projects

Tool	Description
`projects_my_access`	List all projects you can access across all organizations
`projects_list`	List projects in an organization with optional filters (status, search, tags, priority)
`projects_get`	Full project details including charter, milestones, and feedback history
`projects_get_dashboard`	Sprint metrics, completion percentage, and timeline
`projects_get_members`	Project member list with roles — use this to resolve names to user IDs for assignments and @mentions
`projects_get_descoped_tasks`	Tasks flagged by the agentic service for PM review

Sprints

Tool	Description
`sprints_list`	List all sprints for a project
`sprints_get_active`	Get the currently active sprint
`sprints_get`	Full sprint details including progress and feedback
`sprints_get_timeline`	Jira-style timeline view of all sprints and task dates
`sprints_move_tasks`	Move one or more tasks into a sprint

Kanban

Tool	Description
`kanban_get_board`	Full board with columns and tasks (requires `sprint_ids`)
`kanban_create_task`	Create a task in a column — supports name, description (HTML), priority, assignee, labels, sprint, due dates (`due: [start, end]`), and expected hours
`kanban_update_task`	Update task fields — supports the same fields as create, plus actual hours
`kanban_move_task`	Move a task to a different column and optional position
`kanban_delete_task`	Permanently delete a task

Bugs

Tool	Description
`bugs_list`	List bugs with optional severity, status, and assignee filters
`bugs_get`	Full bug details including steps to reproduce and linked commits
`bugs_create`	Report a new bug — supports title, description (HTML), steps to reproduce (HTML), severity, assignee, and expected hours
`bugs_update`	Update bug fields or status — supports the same fields as create, plus actual hours

Comments

Tool	Description
`comments_list`	List comments on a task, bug, or project. Cursor-paginated (newest first, 20 per page). Pass the `cursor` value from the `next` field in the response to fetch the next page.
`comments_create`	Add a comment or reply to a thread
`comments_update`	Edit a comment
`comments_delete`	Delete a comment and its replies
`comments_get_replies`	Get all replies to a comment thread

Commits

Tool	Description
`commits_list`	List GitHub commits linked to a task or bug
`commits_link`	Link a GitHub commit to a task or bug
`commits_unlink`	Remove a commit link

Activity

Tool	Description
`activity_list`	Chronological activity history for a task, bug, or project

Users

Tool	Description
`users_me`	Your user profile
`users_list`	Search or list platform users — for assignee lookups, prefer `projects_get_members` instead

Performance

Tool	Description
`performance_assessments_by_user`	Agentic performance assessments for a specific user — supports optional date range filters
`performance_assessments_by_project`	Agentic performance assessments for all members of a project — supports optional date range filters

Notes

Tool	Description
`notes_list`	List your personal notes — filter by pinned or archived status
`notes_get`	Get a single note
`notes_create`	Create a personal note — supports title, content (HTML), tags (array of strings), color, and pinned status
`notes_update`	Update note fields — supports title, content, tags (array of strings), color, pinned, and archived status
`notes_delete`	Delete a note

Project Docs

Tool	Description
`project_docs_list`	List all doc pages for a project — returns metadata only (id, title, icon, cover_image, parent_id, position, dates). Use this to explore the documentation structure before fetching individual pages.
`project_docs_get`	Get a single doc page with its full BlockNote content. Pass the `project_id` and the `doc_id` (UUID) returned by `project_docs_list`.

Search

Tool	Description
`search_codebase`	Search for code patterns, functions, classes, or text across repositories connected to a project. Provide `project_id` and `query` to search all connected repos. Narrow results with `repo` (`owner/repo` format) or `branch`. Use `top_k` to control result count (default: 5, max: 20).

Troubleshooting

No MCP token available — The token is missing from your config. For IDEs (Cursor, Windsurf, Kiro, VS Code), add x-umaku-token to the headers section. For Claude or ChatGPT, append ?token=mcp_your_token_here to the server URL.
{"error": "...", "status_code": 401} (401 Unauthorized) — Your token is invalid or revoked. Generate a new one at Account Settings → MCP.
kanban_get_board returns empty columns — Pass sprint_ids explicitly. Call sprints_get_active first to get the ID.
Tasks are from the wrong sprint — The board does not default to the active sprint. Always pass the sprint ID explicitly.