MCP Server (AI Assistant Integration)

MantisHub ships an MCP server that connects your MantisHub instance to AI assistants such as Claude, ChatGPT, Gemini, Cursor, and VS Code Copilot. Once connected, you can work with your issue tracker in plain language — ask the assistant to find issues, create and update them, add notes, read and write wiki pages, and search across your projects — without leaving the tool you are already working in.

The MCP server is only available for Platinum + plans. Check out this article to upgrade your plan or reach out to our support team.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools and data sources. An MCP server publishes a set of tools; an MCP-compatible AI client connects to that server and decides which tools to call based on what you ask.

MantisHub's MCP server is served as a path on your own instance:

https://yourmantishubname.mantishub.io/mcp

There is nothing to install or host. Every request carries your API token, so each action is attributed to you and you can only see and change the data you are already authorized to access — exactly the same permissions you have in the web UI, with one exception: a token is always required, so MCP can never be used anonymously, even on an instance that allows anonymous access for signed-out visitors.

Setting Up

Connecting an AI tool takes three steps: create an API token, find your MCP URL, then add the server to your AI tool.

Step 1 — Create an API Token

Log into your MantisHub, click your avatar in the top right-hand corner, select My Account, open the API Tokens tab, enter a name for the token (for example MCP), and click Create.

Copy and save the generated token — it is only displayed once. If you lose it, revoke it and generate a new one. See REST API for more detail on API tokens.

The token carries your permissions. The AI assistant can only see and change what you can see and change.

Step 2 — Find Your MCP URL

Your MCP URL is your normal MantisHub address with /mcp appended, for example https://yourmantishubname.mantishub.io/mcp.

The examples below use https://yourmantishubname.mantishub.io/mcp — substitute your own address.

Step 3 — Add the Server to Your AI Tool

Most AI tools connect to a remote MCP server directly: you supply a URL and an Authorization header containing your API token, in the form Authorization: Bearer YOUR_TOKEN. Paste the token exactly as generated.

Pick your client below.

Claude Code

A single command, with no configuration file to edit:

claude mcp add --transport http mantishub https://yourmantishubname.mantishub.io/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

By default the server is added at local scope — available only to you, and only in the current project. Use the --scope (-s) flag to change where it is registered:

• User scope makes the server available to you across every project on your machine. Because your API token carries your own permissions, this is usually the right choice:

  claude mcp add --scope user --transport http mantishub https://yourmantishubname.mantishub.io/mcp \
    --header "Authorization: Bearer YOUR_TOKEN"

• Project scope writes the server to a .mcp.json file in the project root that is shared with everyone who works in that project. Because the file is shared, point the header at an environment variable rather than a literal token, so each teammate connects with their own:

  claude mcp add --scope project --transport http mantishub https://yourmantishubname.mantishub.io/mcp \
    --header 'Authorization: Bearer ${MANTISHUB_TOKEN}'

  Note the single quotes: they stop your shell from substituting the value, so the literal ${MANTISHUB_TOKEN} is what gets written into .mcp.json. Claude Code expands it when it connects. Everyone on the project then sets MANTISHUB_TOKEN to their own API token in their shell profile — one shared configuration file, one token per person.

  WARNING

  If you paste the token directly into the command instead, .mcp.json will contain your personal API token. Make sure it is not committed to source control — add it to .gitignore — so your token is not shared.

Use claude mcp list to confirm it registered, and claude mcp remove mantishub to remove it. Add --scope user to remove if you registered the server at user scope.

If you ran these commands from a separate terminal while Claude Code was already open, restart Claude Code so it picks up the change.

Claude Desktop

Claude Desktop launches MCP servers as local processes and cannot dial a remote URL directly, so it uses the mcp-remote bridge. This requires Node.js 18 or higher to be installed.

Edit the Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mantishub": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://yourmantishubname.mantishub.io/mcp",
        "--header",
        "Authorization:${MANTIS_AUTH}"
      ],
      "env": {
        "MANTIS_AUTH": "YOUR_TOKEN"
      }
    }
  }
}

Then fully quit and reopen Claude Desktop — closing the window is not enough.

WARNING

Note that the header is written as Authorization:${MANTIS_AUTH} with no space after the colon, that the token is supplied through the env block, and that the Bearer prefix is omitted here. Claude Desktop splits each argument on whitespace, so any space in this value — from the token written inline, or from a prefix — breaks the header in two. This is a constraint of the mcp-remote bridge and applies only to Claude Desktop. It is the most common reason a Claude Desktop setup fails.

ChatGPT / Codex

Go to Settings → MCP Servers → Add Server and enter:

• Name: mantishub
• Transport: Streamable HTTP
• URL: https://yourmantishubname.mantishub.io/mcp
• Headers: key Authorization, value Bearer YOUR_TOKEN

Cursor, VS Code, and Other Remote-Capable Clients

Add the following to the client's MCP configuration (Cursor: Settings → MCP → Add; VS Code: your mcp.json):

{
  "mcpServers": {
    "mantishub": {
      "url": "https://yourmantishubname.mantishub.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Antigravity IDE

Go to Agent → MCP Servers → Manage MCP Servers → View Raw Config and paste:

{
  "mcpServers": {
    "mantishub": {
      "serverUrl": "https://yourmantishubname.mantishub.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Verifying the Connection

In any connected client, ask:

What should I work on next?

The assistant should use the MCP connection to reach your instance and answer using issues from MantisHub — for example, the ones assigned to you.

What You Can Do

The MCP server exposes tools for issues, notes, projects, users, wiki pages, saved filters, and instance configuration. Some examples of what you can ask for:

Issues

• "Show me all critical bugs assigned to me"
• "Create an issue to fix the flaky test above under project XYZ and assign to John"
• "Resolve issue 1234 and add a note saying the fix is deployed"
• "Assign issue 1234 to John and change its priority to urgent"

Notes

• "Add a note to 1234 saying I'll look at this tomorrow"
• "Summarize the discussion on issue 1234"

Search

• "Find all open issues related to payments"
• "Show me issues created this week by John"
• "List all issues tagged with security, newest first"
• "Summarize all feature requests relating to our analytics feature and suggest the top 3 features to implement next"

Wiki Pages

• "Show me the wiki page for the authentication module"
• "Implement the design documented in the 'single sign-on' wiki page"
• "Based on the feature implemented on this branch, create a wiki page with user documentation for the feature"
• "Update the 'single sign-on' wiki page to reflect the latest changes"
• "Analyze the code and write up a wiki page with a proposal to make our tests pass faster"

Projects, Users, and Configuration

You rarely need to ask about these directly. Instead, the assistant looks them up on its own to complete a higher-level request. When you say "create an issue in project XYZ and assign it to John," it resolves XYZ against the projects you have access to and John against the users on that project before it creates anything.

Because every instance has its own projects, priorities, severities, statuses, categories, and custom fields, the assistant can query those first, so the values it submits are ones your instance actually accepts. You can still ask directly when you want to — for example, "list the projects I have access to" or "what priorities are available in this instance?" — but most of the time these lookups happen behind the scenes.

Security

Working through an AI assistant does not use a separate permission model. Every request is made with your API token and goes through the same authorization MantisHub already enforces — anything you cannot do in the web UI cannot be done through an AI assistant.

• Never anonymous. A request that arrives without an Authorization header is rejected with HTTP 401 before any data is read. An API token is always required, so MCP is not supported for users relying on anonymous access — unregistered users cannot generate an API token.
• Encrypted in transit. All traffic uses HTTPS, inheriting your instance's TLS certificate. Authorization headers are never written to logs.
• Rate limited. Requests are capped per API token so that an automated agent cannot overload your instance — see Rate Limits.
• Revocable at any time. Revoke the token in My Account → API Tokens to immediately cut off any AI tool using it, without affecting your password or other integrations.

Rate Limits

MCP requests are capped at 250 per minute, per API token, in a one-minute window that resets sixty seconds after your first request. Each token gets its own budget, so a colleague's busy AI agent never uses up yours — and if you connect several tools with a token each, one of them running hot does not throttle the others.

When the rate limit is exceeded. The request is rejected with HTTP 429, and the response tells your AI tool how many seconds to wait before trying again. Nothing is lost — the request simply did not run, and can be repeated once the window resets.

Bulk operations. Each request the assistant makes counts once, no matter how much work it does — a request that touches several records still costs one. What multiplies is the assistant's own looping: it works an issue at a time, so "update these sixty issues" becomes sixty requests. If a long run is being throttled, ask it to work in smaller batches — "update these ten at a time" — or to prefer a single search over many individual lookups.

Anti-spam limits on write actions. Separately from the cap above, MantisHub limits how often a newly signed-up account can create content — reporting issues, adding notes, tags, and attachments. It applies to the account rather than the way it connects, so the same limit is in force in the web UI, through the REST API, and through MCP. If writes are being rejected while reads keep working, this is the more likely cause — see User Blocked to Avoid Spam for the defaults and how to adjust them.

Troubleshooting

Authentication or permission errors. Confirm the token was pasted whole and has not been revoked — a truncated or partially copied token is the usual cause. Check the Last Used column in My Account → API Tokens to see whether the token is being used at all.

"Missing Authorization header" or a 401 on connect. The tool is connecting without a token — check that the Authorization header is configured and actually being sent. An API token is always required, so this fails the same way whether or not anonymous access is enabled on your instance. If instead the tools appear and only the calls fail with an authentication error, the header is being sent but the token is wrong or revoked.

Claude Desktop shows no MantisHub tools. Check that -y is present in the args array, that the header uses the no-space Authorization:${MANTIS_AUTH} form described above, and that the JSON is valid — an invalid configuration file is silently ignored. You can test the bridge directly with:

npx -y mcp-remote https://yourmantishubname.mantishub.io/mcp --header "Authorization:YOUR_TOKEN"

Claude Desktop logs are in ~/Library/Logs/Claude/mcp*.log on macOS and %APPDATA%\Claude\logs\ on Windows.

The assistant used an invalid priority, status, or custom field value. Ask it to check the instance configuration first — for example, "check the available priorities in MantisHub, then create the issue."

Requests are being throttled. You have reached your own rate limit. The response tells your AI tool how many seconds until your window resets, and waiting that long clears it. If a bulk operation keeps being rejected, ask the assistant to work in smaller batches; see Rate Limits for detail, or contact MantisHub support.