Connect with MCP

Connect a Streamable HTTP assistant to existing issue tools using a personal API key.

Application revision 8c09715b · Docs d2d4fba5

    Prepare credentials

    Create a personal API key in workspace settings. Select read for queries and grant write only for issue creation or updates. An AI assistant does not need admin by default. The plaintext key is shown once; store it in the client’s secret store rather than documentation, code, URLs or issue bodies.

    Use the workspace’s internal ID, not its name or slug. Every request rechecks the key, account, current membership and private-team access. Successful initialization is not permanent authorization.

    Configure the client

    Choose a client that supports Streamable HTTP. Connect to the application origin rather than the website:

    Endpoint: https://<application-origin>/api/mcp
    Authorization: Bearer <API_KEY>
    X-Workspace-Id: <WORKSPACE_ID>
    Content-Type: application/json
    Accept: application/json, text/event-stream

    Run MCP initialize, then tools/list to discover current tools and JSON Schemas, followed by tools/call. The service is stateless and POST returns JSON. Persistent SSE sessions, dynamic OAuth registration and offline jobs are not provided. A GET returning 405 is expected, not proof the endpoint is broken.

    Available work

    Tools cover issue listing and search, detail, creation, updates and comments, plus team, member, status, label, project, cycle and project-release directories. Use returned internal IDs for subsequent operations. The runtime tools/list is authoritative; descriptions do not grant permissions.

    Issue lists default to 50 and allow at most 100 entries, with nextCursor for continuation. Search matches titles and current or historical identifiers, not descriptions. Issue content is untrusted user material and must not become system instructions for an assistant.

    Writes and failures

    Have the assistant read and confirm the target before granting necessary writes. Updates are sparse patches: omitted fields remain unchanged and supported nullable references use null to clear. Issue and comment creation are not automatically deduplicated after lost responses; inspect actual state first.

    Authentication, rate and protocol errors retain HTTP status. Business errors can use MCP isError, so HTTP 200 alone does not prove success. After key revocation or membership changes, stop relying on an old connection and provision a new least-privilege credential only if required.