How to connect an MCP client

Vantik speaks the Model Context Protocol. An LLM agent therefore creates, picks up, notes, and closes an issue, and it searches the past work. Claude Code, Cursor, and any other client with MCP can do this, and you connect no REST endpoint by hand. The server gives a set of tools with the shape of a task. The difficult parts happen on the server: it finds the id of ENG-42, it converts the markdown, and it posts a resolution before it closes an issue.

The endpoint is:

POST /v1/mcp

It is a stateless MCP server with the Streamable HTTP transport. It uses the same authentication with a personal access token as the other parts of the API. The token travels in the Authorization header.

How to get a token

Make a token in Vantik → Settings → Agents. An agent account is a separate identity in the workspace. The workspace therefore records each issue and each note against the agent, and not against you. When you make the account, the page shows the token one time. It also shows a .mcp.json file and a claude mcp add command that you can copy. Copy them at that moment, because you cannot read the token again.

note

Only an administrator can make an agent. If you do not see Settings → Agents, ask an administrator of the workspace to make the agent and to give you its configuration.

How to connect Claude Code

Add the server to the .mcp.json file of a project. Use your own host and your own token:

{
  "mcpServers": {
    "vantik": {
      "type": "http",
      "url": "https://your-vantik-host/api/v1/mcp",
      "headers": { "Authorization": "Bearer tg_pat_…" }
    }
  }
}

You can also register the server from the command line:

claude mcp add --transport http vantik https://your-vantik-host/api/v1/mcp \
  --header "Authorization: Bearer tg_pat_…"

warning

Do not commit a live token. The .mcp.json file of a project usually goes into version control, and this file holds a token that reads and writes the workspace. Keep the file out of version control, or register the server for your user only. claude mcp add writes to ~/.claude.json, which is not in the repository. If a commit does hold a token, revoke that agent in Settings → Agents and make a new one.

How to connect another client

Any MCP client with the Streamable HTTP transport connects in the same way. Point it at https://your-vantik-host/api/v1/mcp, and send the token in an Authorization: Bearer header. The /api prefix is the webapp proxy in front of the server. If you call the server directly, remove that prefix and use /v1/mcp.

The tools

Tool	What it does
list_tasks	Lists the tasks as small rows. You can filter by team, assignee, state, labels, priority, and project.
get_task	Gives everything about one task in one call: the description, the notes, the history, the sub-tasks, and the relations.
search_tasks	Searches the titles, the descriptions, and the notes. Set stateCategory: ["COMPLETED"] to find an earlier fix with its resolution.
find_similar_tasks	Gives the earlier tasks that are similar to one task, and the resolution of each.
create_task	Files an issue. It holds an issue to a minimum: a real description, and acceptance criteria for a top-level issue.
update_task	Changes the title, the description, the state, the labels, the priority, the assignee, or the project of a task.
list_projects	Gives the projects of the workspace. A project is an objective, and the issues group under it.
create_project	Opens a project for an objective that truly needs several issues.
pick_up_task	Takes ownership of a task. It assigns the task and moves it to the in-progress state.
add_note	Puts a markdown note on a task, and the search finds that note.
close_task	Closes a task. It first records the resolution as a note, so the search finds the fix later.

Each tool uses the REST API from How to work with agents. Read that page for the endpoints below the tools, or for a client that you build directly against the API.

Rate limits

The endpoint has a rate limit for each token. An agent in a loop therefore limits only itself. Above the limit you get HTTP 429, a Retry-After header, and a JSON-RPC error body. The body holds the same wait time in data.retryAfter.

Variable	Default	What it sets
MCP_RATE_LIMIT	120	The number of requests that one token can make in one window. 0 stops the limit.
MCP_RATE_LIMIT_WINDOW_MS	60000	The length of the window, in milliseconds.

The counters live in the server process. Across several replicas, the real limit is therefore the limit multiplied by the number of replicas. That is enough to stop a loop that runs away. For a true quota, put your own limiter in front of the server and set MCP_RATE_LIMIT=0.

Optional: a house style for a new issue

The configuration above is all that an agent needs to read and to file an issue. But an agent alone files many small issues. It opens a new issue where a note on an issue that exists is enough, and it divides one piece of work into six issues.

working-vantik-issues is a short guide that corrects this behaviour. It says to file fewer and larger issues. It says to group the issues of one objective under a project. It says to add a note to an issue that exists, and not to open a near-duplicate. It also says to write the definition of "done" before you file the issue.

Settings → Agents gives you this guide in the form that your tool reads. Select the tab for your harness, and take the download and the install command next to it. The server serves the files at /v1/agent-skill/:file:

Tool	File	Where it goes
Claude Code	SKILL.md	.claude/skills/working-vantik-issues/SKILL.md
Claude Code	CLAUDE.md	CLAUDE.md, to hold it in the context always
Cursor	working-vantik-issues.mdc	.cursor/rules/
Codex, and any other tool	AGENTS.md	the root of your project

The server makes two of these files from the same source text, so there is one source of truth and not four copies that become different. The originals are in apps/docs/skills/working-vantik-issues/.

This guide sits above the create_task tool, and that tool already refuses an issue with no description or no acceptance criteria. The tool sets the minimum. The guide gives the judgement about what to file.