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.

Caution

Treat your MCP token like a password. Do not commit it to version control.

Setup

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

Cursor

~/.cursor/mcp.json

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

Windsurf

~/.codeium/windsurf/mcp_config.json

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

Kiro

~/.kiro/settings/mcp.json

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

VS Code

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:

.vscode/mcp.json

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

Or via settings.json:

settings.json

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

Claude

Claude supports MCP connectors via the Connectors settings page.

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

Tip

Claude’s connector dialog does not support custom headers. Instead, append your token to the URL as a query parameter: https://mcp.umaku.ai/mcp?token=mcp_your_token_here. The MCP server will extract it automatically.

ChatGPT

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

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

Tip

Same as Claude — append your token to the URL as a query parameter since ChatGPT’s connector UI doesn’t support custom headers.

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 personal or project notes — filter by project, pinned, or archived status
notes_get	Get a single note
notes_create	Create a note — supports title, content (HTML), project, 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

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.