MCP Server

xpntl exposes a full MCP tool surface so coding agents can read issues, post updates, and transition state — all authenticated with scoped harness keys.

Hosted Setup

The xpntl MCP server runs at mcp.xpntl.dev/mcp — no infrastructure required. It uses Streamable HTTP transport with per-session state.

1. Generate a harness key

In the xpntl web app, the quickest path is Settings → Team: add an agent, then click Connect to generate an agent-bound key with copy-paste MCP setup for your harness. You can also manage workspace keys under Settings → Plan & Billing in the Coding Harness Keys section. Either way, copy the key — it starts with xpntl_hk_ and is shown only once.

Harness keys are scoped to a single workspace. Each agent or coding harness should use its own key for audit traceability.

2. Configure your MCP client

Add the server to your client's MCP configuration. The first tool call in every session must be xpntl_authenticate with your harness key.

Claude Code

Add to .claude/settings.json (project or global):

{
  "mcpServers": {
    "xpntl": {
      "type": "url",
      "url": "https://mcp.xpntl.dev/mcp"
    }
  }
}

On first use, Claude Code will call xpntl_authenticate with your harness key. You can also pass it via headers:

{
  "mcpServers": {
    "xpntl": {
      "type": "url",
      "url": "https://mcp.xpntl.dev/mcp",
      "headers": {
        "Authorization": "Bearer xpntl_hk_..."
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "xpntl": {
      "url": "https://mcp.xpntl.dev/mcp"
    }
  }
}

Any MCP client

Point your client at https://mcp.xpntl.dev/mcp using the Streamable HTTP transport. The server responds to POST with JSON-RPC. Sessions are identified by the Mcp-Session-Id header returned in the initialize response.

Self-Hosted Setup

If you self-host xpntl, the MCP server is built into the API container. It's mounted at /mcp on whatever host your API runs on.

# If your API runs at https://xpntl.example.com
# MCP endpoint is https://xpntl.example.com/mcp

# Health check
curl https://xpntl.example.com/mcp/health
# → { "status": "ok", "sessions": 0 }

Standalone mode

The MCP server can also run standalone via stdio (for local development or custom setups):

# Stdio transport (pipes)
node apps/mcp/dist/index.js

# HTTP transport (port 3100)
node apps/mcp/dist/http.js

Tool Reference

The xpntl MCP server exposes 28 tools spanning issues, comments, your agent inbox, workflow states, labels, projects, workspace docs, teams, and users. Every tool except xpntl_authenticate requires a valid session — call authenticate first (or pass your key via the Authorization: Bearer header and the session is established for you).

Authentication

Tool	Description
`xpntl_authenticate`	Authenticate with a harness key. Must be called before any other tool. Params: `key` (string) — your `xpntl_hk_...` key

Issues

Tool	Description
`xpntl_issue_list`	List/search issues with full-text search and filters. Params: `q`, `stateType`, `priority`, `assigneeId`, `includeSubIssues`, `limit`
`xpntl_issue_get`	Get a single issue by key (e.g. `ACME-42`). Params: `key`
`xpntl_issue_create`	Create a new issue with optional state, assignee, project, labels, and parent. Params: `title`, `description`, `priority`, `stateId`, `assigneeId`, `projectId`, `labelIds`, `parentKey`
`xpntl_issue_update`	Update an existing issue by key. Params: `key`, `title`, `description`, `priority`, `stateId`, `assigneeId`
`xpntl_issue_bulk_update`	Update multiple issues at once. Params: `keys`, `stateId`, `priority`, `assigneeId`
`xpntl_issue_delete`	Soft-delete an issue (can be restored later). Params: `key`
`xpntl_issue_assign`	Assign a user to an issue. Params: `key`, `userId`
`xpntl_issue_unassign`	Remove a user from an issue. Params: `key`, `userId`

Comments

Tool	Description
`xpntl_comment_list`	List comments on an issue. Params: `key`
`xpntl_comment_create`	Post a comment on an issue (markdown supported). Params: `key`, `body`

Inbox & Notifications

Agents pick up work the same way humans do — through @mentions, assignments, and comment replies. xpntl_inbox is the one-call way to do it: poll it, act, reply, and mark items read.

Tool	Description
`xpntl_inbox`	Your actionable inbox in one call — unread @mentions, assignments, and comment replies, each already enriched with the issue (key, title, state, priority, URL), the comment/mention text, and who triggered it, so you can act with no follow-up lookups. Params: `types`, `includeRead`, `limit`
`xpntl_notification_list`	List raw notifications for the authenticated user/agent. Params: `unreadOnly`, `limit`
`xpntl_notification_mark_read`	Mark a notification as read after acting on it, so you don't process it again. Params: `id`

Workflow States

Tool	Description
`xpntl_workflow_state_list`	List all workflow states. Use these IDs when creating/updating issues. Returns: `id`, `name`, `type`, `position`

Labels

Tool	Description
`xpntl_label_list`	List all labels in the workspace.
`xpntl_label_create`	Create a new label. Params: `name`, `color`, `description`
`xpntl_label_add`	Add a label to an issue. Params: `key`, `labelId`
`xpntl_label_remove`	Remove a label from an issue. Params: `key`, `labelId`

Projects & Teams

Tool	Description
`xpntl_project_list`	List all projects in the workspace.
`xpntl_project_create`	Create a new project. Params: `name`, `key` (2–10 uppercase chars), `description`
`xpntl_team_list`	List all teams in the workspace.

Docs

Workspace docs are the nestable wiki pages shown under Docs in the web app. Agents can read and maintain them — specs, runbooks, ADRs — the same way they manage issues. Docs are markdown; xpntl_doc_list returns metadata only, so fetch a doc to read its body.

Tool	Description
`xpntl_doc_list`	List workspace docs (metadata only — id, title, projectId, parentId, updatedAt). `parentId` lets you reconstruct the page tree. Params: `projectId` (optional filter)
`xpntl_doc_get`	Get a single doc by id, including its full markdown content. Params: `id`
`xpntl_doc_create`	Create a new doc (markdown), optionally scoped to a project or nested under a parent. Params: `title`, `content`, `projectId`, `parentId`
`xpntl_doc_update`	Update a doc by id. Editing content saves the previous version as a revision; pass `parentId` to move it in the tree. Params: `id`, `title`, `content`, `parentId`
`xpntl_doc_delete`	Delete a doc by id (admin only). Sub-pages are re-homed under the deleted doc's parent. Params: `id`

Users

Tool	Description
`xpntl_user_list`	List workspace members. Use these IDs when assigning issues. Returns: `id`, `email`, `displayName`, `role`

Priority Values

Value	Meaning
`0`	No priority
`1`	Urgent
`2`	High
`3`	Medium
`4`	Low

Workflow State Types

Type	Default State
`triage`	Triage
`backlog`	Backlog
`unstarted`	Todo
`started`	In Progress
`completed`	Done
`canceled`	Canceled

Health Check

GET /mcp/health
→ { "status": "ok", "sessions": 3 }

Returns the number of active MCP sessions. Use this to verify the server is running and reachable.