Vulcan MCP Server

An MCP (Model Context Protocol) server that lets you manage Vulcan tasks directly from Claude Code or any MCP-compatible AI tool.

Quick Start

1. Generate an API Token

1. Open your Vulcan app → Settings → API Tokens
2. Enter a name (e.g. "Claude Code") and choose an expiry
3. Click Generate Token
4. Copy the token (vulcan_ak_...) — it is only shown once

2. Install Dependencies

cd mcp-server
npm install

3. Configure Claude Code

Create a .mcp.json file in your project root (the directory where you run Claude Code):

{
  "mcpServers": {
    "vulcan": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/index.js"],
      "env": {
        "VULCAN_TOKEN": "vulcan_ak_your_token_here",
        "VULCAN_API_URL": "https://your-vulcan-instance.com/api/v1"
      }
    }
  }
}

Tip: Use an absolute path for args so the server works regardless of your working directory.

Important: Add .mcp.json to your .gitignore — it contains your API token.

4. Verify

Start Claude Code in your project directory. Ask:

"Check my Vulcan auth status"

If configured correctly, Claude will respond with your name and email.

Hierarchy & Typical Call Flow

Vulcan's domain model is hierarchical, and MCP tools navigate it by passing IDs returned from one call into the next. Tenant scope is implicit: your API token resolves to a user, which pins every call to that user's tenant_<id> MongoDB database — there's no tenantId parameter. Permissions (OpenFGA) are inherited from the token holder.

Tenant (implicit via token)
 └── Project ────────────────────────────────── Document tree (parallel)
      ├── Member / Invite                        ├── Document
      ├── Space (grouping)                       │    ├── Version  (history + restore)
      ├── Column (status / kanban)               │    ├── Comment
      ├── Sprint                                 │    └── Review / Approval
      ├── Tag                                    └── (rename / delete)
      └── Task
           ├── Subtask (Task with parent)
           ├── Comment
           ├── Attachment
           ├── Task Link  (relates two tasks: blocks, duplicates, etc.)
           ├── External Link  (URL → 3rd party: PR, Figma, etc.)
           └── Work Log / Activity

Example chain — "create a bug in the active sprint and assign it to Gagan":

1. list_projects → pick projectId
2. list_members(projectId) → find Gagan's userId
3. get_active_sprint(projectId) → sprintId
4. list_columns(projectId) → find the "Bug Triage" columnId
5. create_task(projectId, type: "bug", title, assignee_id, column_id) → taskId
6. assign_sprint(taskId, sprintId)
7. add_comment(taskId, "Reproduces on staging")

Available Tools (94)

Auth (1)

| Tool | Description | | ------------- | ----------------------------------- | | auth_status | Check current authentication status |

Projects (6)

| Tool | Description | | --------------------- | -------------------------------------------- | | list_projects | List all projects you have access to | | get_project | Get a project by ID | | get_project_by_code | Look up a project by its short code (e.g. MOB) | | create_project | Create a new project (you become the owner) | | update_project | Update project fields | | delete_project | Delete a project |

Project Members & Invites (8)

| Tool | Description | | ----------------------------- | ---------------------------------------------------- | | list_members | List project members (use to find user IDs) | | add_project_member | Add an existing user to a project | | remove_project_member | Remove a member from a project | | update_project_member_role | Change a member's project role | | invite_to_project | Invite a user (by email) directly to a project | | create_invite | Create a tenant-level invite | | list_invites | List pending invites | | revoke_invite | Revoke a pending invite |

Spaces (7)

Spaces are project sub-groupings (e.g. "Backend", "Mobile") that bucket tasks within a project.

| Tool | Description | | ------------------- | -------------------------------------------- | | list_spaces | List spaces in a project | | get_space | Get a space by ID | | create_space | Create a space under a project | | update_space | Update space fields | | delete_space | Delete a space | | reorder_spaces | Reorder spaces within a project | | move_space_tasks | Move all tasks from one space to another |

Columns (6)

Columns are the kanban statuses (To Do, In Progress, Done, …) used by move_task.

| Tool | Description | | ------------------ | -------------------------------------------- | | list_columns | List columns for a project | | get_column | Get a column by ID | | create_column | Create a new status column | | update_column | Rename or restyle a column | | delete_column | Delete a column | | reorder_columns | Reorder columns within a project |

Sprints (8)

| Tool | Description | | ------------------- | ------------------------------------------------------ | | list_sprints | List sprints for a project | | get_sprint | Get a sprint by ID | | get_active_sprint | Get the currently-active sprint for a project | | create_sprint | Create a new sprint | | update_sprint | Update sprint name, dates, or goal | | start_sprint | Start a planned sprint | | complete_sprint | Complete an active sprint | | delete_sprint | Delete a sprint |

Tasks (8)

| Tool | Description | | --------------------- | -------------------------------------------------------------------------------- | | list_tasks | List tasks with filters (project, sprint, assignee, type, priority, search) | | get_task | Get detailed info about a single task | | create_task | Create a task (use parent_id to make a subtask) | | update_task | Update task fields (title, description, priority, type, points, dates, assignee) | | delete_task | Delete a task (requires owner or admin role) | | move_task | Move a task to a different column (status) | | move_task_to_space | Move a task to a different space | | assign_sprint | Assign or remove a task from a sprint |

Task Hierarchy (2)

| Tool | Description | | --------------- | ---------------------------------------------------------- | | get_ancestry | Get the parent chain for a task (subtask → parent → root) | | list_children | List child/subtask records under a task |

Task Links (4)

Typed relationships between two tasks (blocks, is-blocked-by, duplicates, relates-to, etc.).

| Tool | Description | | ---------------------------- | -------------------------------------------------------- | | list_task_links | List links on a task | | list_available_task_links | List valid link types you can create | | create_task_link | Create a typed link between two tasks | | delete_task_link | Remove a task link |

External Links (3)

URL links from a task to external systems (GitHub PRs, Figma, Confluence, …).

| Tool | Description | | ----------------------- | ------------------------------------ | | list_external_links | List external links on a task | | create_external_link | Attach an external URL to a task | | delete_external_link | Remove an external link |

Tags (5)

| Tool | Description | | ------------- | ---------------------------- | | list_tags | List tags in a project | | get_tag | Get a tag by ID | | create_tag | Create a new tag | | update_tag | Rename or recolor a tag | | delete_tag | Delete a tag |

Comments (5)

Works on both tasks and documents (see also list_document_comments).

| Tool | Description | | ----------------- | -------------------------------------- | | list_comments | List comments on a task | | get_comment | Get a single comment by ID | | add_comment | Add a comment to a task | | update_comment | Edit a comment | | delete_comment | Delete a comment |

Attachments (3)

| Tool | Description | | -------------------- | --------------------------------------------------------------------------- | | list_attachments | List file attachments on a task | | upload_attachment | Upload an attachment (base64 or URL — large binaries are impractical over stdio) | | delete_attachment | Delete an attachment |

Note: For large files, prefer the Vulcan web UI — base64 over stdio works only for small payloads.

Documents (5)

Documents are a parallel tree under a project (specs, runbooks, design docs) with versioning and an approval workflow.

| Tool | Description | | ------------------ | ------------------------------------ | | list_documents | List documents in a project | | get_document | Fetch a document's content | | update_document | Update body or metadata | | rename_document | Rename a document | | delete_document | Delete a document |

Document Versions (3)

| Tool | Description | | ---------------------------- | ---------------------------------------- | | list_document_versions | List historical versions | | get_document_version | Fetch a specific version's content | | restore_document_version | Roll a document back to a prior version |

Document Review & Approval (6)

| Tool | Description | | ------------------------------- | -------------------------------------------------------- | | submit_document_for_review | Submit a document into the review workflow | | approve_document | Approve a document under review | | reject_document | Reject a document under review | | get_document_approvals | List approval/rejection decisions for a document | | list_pending_document_reviews | List documents currently awaiting your review | | list_document_comments | List comments left on a document |

Activity & Work Logs (7)

| Tool | Description | | -------------------------- | -------------------------------------------------------- | | task_activity | Activity timeline for a specific task | | project_activity | Activity timeline for a project | | my_activity | Your own recent activity across the tenant | | recent_activity | Tenant-wide recent activity | | activity_summary | Aggregated summary (counts, top contributors, etc.) | | task_work_log | Time-tracking / work log entries on a task | | update_work_log_summary | Edit the summary text on a work log entry |

Notifications (4)

| Tool | Description | | ------------------------------- | --------------------------------- | | list_notifications | List your notifications | | mark_notification_read | Mark a single notification read | | mark_all_notifications_read | Mark all notifications read | | dismiss_notification | Dismiss a notification |

Templates (3)

| Tool | Description | | -------------------------- | ------------------------------------------------------------ | | list_project_templates | List available project templates | | get_project_template | Fetch a template definition | | save_stages_as_template | Save the current column/stage layout as a reusable template |

Example Usage in Claude Code

"List all my Vulcan projects"
"Create a new project called 'Mobile App' with code 'MOB'"
"Show me the open bugs in project X"
"Create a task titled 'Fix login redirect' as a bug with high priority in project X"
"Assign task PROJ-42 to Gagan"
"Move task PRJ-42 to the Done column"
"Add a comment to PROJ-42: Fixed in commit abc123"
"Create a sprint 'March Release' from March 10 to March 24"
"What's the status of sprint 'March Release'?"

Environment Variables

| Variable | Required | Default | Description | | ---------------- | -------- | ------------------------------ | ------------------------------------------- | | VULCAN_TOKEN | Yes | — | API token from Vulcan Settings → API Tokens | | VULCAN_API_URL | No | http://localhost:3000/api/v1 | Vulcan API base URL |

Token Management

• Tokens can be created, viewed, and revoked in Settings → API Tokens
• Each token shows its prefix, last used date, and usage count
• Tokens support optional expiry (30, 90, 180, 365 days, or never)
• Revoked or expired tokens stop working immediately