AI Agent Integration & Agent Tools (MCP)

Connect an AI agent — Claude Code, your own in-house agent, or an RPA bot — to read and act on your tickets through a governed set of tools. Every agent authenticates with a scoped, revocable token, sees only the tools it is allowed to use, and is held to the same rules of done as your human team. This guide covers issuing agent tokens, connecting over MCP, the full tool catalog, workflow Definition-of-Done gates, and the governance and audit rails that keep it safe.

Overview

RapiDesq is more than a place your team works — it is a place your AI agents can work too. The platform exposes a governed catalog of ticket tools (read, write, and state-changing actions) that any AI agent can call to discover work, do it, attach evidence, and move a ticket through your workflow — all under a scoped credential and a full audit trail.

The division of labor is deliberate. The platform is the control plane; the agent is an external actor that calls tools. RapiDesq owns:

• What work exists — the tickets, their fields, and their current status.
• Which tools an agent may call — a per-token tool allowlist combined with a permission scope.
• The rules of done — the Definition of Done attached to each workflow status, and the gate every state-changing action must pass.
• The immutable record — a full, attributable audit of every tool call the agent made.

The agent supplies the intelligence; the platform supplies the governed levers and the rulebook. You never hand an agent unbounded access — you hand it a token that can call a specific set of tools, on a specific set of tickets, subject to specific gates.

What you can connect

• Claude Code — a coding agent that discovers work assigned to it, does the build, and advances a gated workflow through stages like Review and Testing.
• A triage agent — reads incoming tickets, categorizes them, sets fields, and routes them — without the ability to resolve.
• A reporting or read-only agent — queries tickets and workflows without changing anything.
• Your own bespoke agent or RPA bot — any client that speaks the Model Context Protocol (MCP), scoped to exactly the tools you grant it.

If you'd rather not host an agent at all, Ticket Automation Rules give you the same idea as a managed feature: an AI lane puts a platform-run AI worker on every ticket entering a status you nominate and drives it toward a target status, using this same governed tool surface and the same workflow gates — configured entirely in the admin UI. The two are complementary: bring your own agent when the work needs your code, your context, or your repository; use an AI lane when it doesn't.

How It Works

The integration follows the open Model Context Protocol (MCP) — the same standard AI agents use to discover and call tools. At a high level:

1. A tenant administrator issues a scoped agent token bound to a machine-worker identity, choosing a persona that sets sensible defaults.
2. The agent connects to RapiDesq's MCP endpoint, sending the token as a credential.
3. The agent asks the endpoint which tools it can use. It sees only the tools that token is allowed to call.
4. The agent calls tools — pull a ticket, claim it, attach evidence, post an update, advance it to the next status — and every call is checked against the token's scope and the workflow's gates, then recorded.

Because RapiDesq never runs the agent itself, the agent lives wherever you run it: a customer's repository and CI, an automation host, or a developer's machine. It reaches the platform only through the credential you issue and the tools you allow.

Prerequisites

• Administrator access to RapiDesq — issuing agent tokens and configuring workflows is an admin capability.
• An MCP-capable agent — Claude Code, your own agent built on an MCP client library, or any MCP-speaking automation.
• A configured ticket workflow (recommended) — if you want agents to move work through gated stages with evidence, set up your statuses and Definitions of Done first (see Workflows & Definition of Done). Read-only and simple write access work without any workflow configuration.

Agent Tokens

An agent token is how an AI agent authenticates to RapiDesq. It is issued by a tenant administrator and is bound to a dedicated machine-worker identity — a service account that is separate from any human login and does not consume a user seat. This keeps agent activity cleanly attributable and separate from your people.

Issuing a token

From the admin area, create a new agent token. You provide:

• Name — a label so you can recognize the agent later (for example, "ci-coding-agent" or "inbound-triage-bot").
• Persona — a preset that sets a sensible default tool allowlist and permission scope (see below). You can fine-tune the scope after choosing a persona.
• Mode — Live (actions take effect) or Dry-run (actions are validated but never applied — ideal for a safe first connection).
• Expiry — an optional lifetime after which the token stops working.

Persona presets

Personas save you from assembling a tool set and permission scope by hand. Each one grants a least-privilege default that fits a common kind of agent:

A persona is a starting point, not a straitjacket — after issuing a token you can tighten its tool allowlist or the tickets it may touch. The effective access of any token is always the intersection of its persona scope, its tool allowlist, and the tickets it is scoped to.

Connecting over MCP

RapiDesq exposes an MCP endpoint over HTTP. Your agent connects to it and sends the agent token as a Bearer credential. The endpoint is on the RapiDesq-hosted API for your workspace — the same URL for every project on your account. It is not your own website domain:

https://<your-rapidesq-api-host>/api/v1/mcp

You don't have to guess the host. Open Settings → Agent Tokens in RapiDesq: the Connect over MCP panel shows your exact endpoint with a copy button, and issuing a token opens a dialog with a ready-to-paste .mcp.json that already has your real host and token filled in — just like the chat widget's Get Embed Code.

Claude Code configuration

To connect Claude Code, add the RapiDesq server to your .mcp.json. The Agent Tokens dialog generates this for you with the host and token already in place; the shape is:

{
  "mcpServers": {
    "rapidesq": {
      "type": "http",
      "url": "https://<your-rapidesq-api-host>/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer rasq_agt_REPLACE_WITH_YOUR_TOKEN"
      }
    }
  }
}

If you're assembling it by hand, copy the endpoint from the Connect over MCP panel and paste the token you saved when you issued it (it is shown only once). Any other MCP client connects the same way: an HTTP MCP endpoint with an Authorization: Bearer header.

Discovering available tools

Once connected, the agent asks the endpoint for its tool list. RapiDesq returns only the tools that token is allowed to use — the intersection of the token's tool allowlist and the permissions it holds. A Read-only token, a Triage token, and a Worker token each see a different set. This means an agent physically cannot call a tool it wasn't granted; the tool simply isn't there.

The Tool Catalog

The tools fall into three tiers — read (look at work), write (add information to a ticket), and action (change a ticket's state through the workflow). The last column shows which personas include each tool by default.

Example: calling a tool

Tools are called with a name and a set of arguments. For example, advancing a ticket to a Review status with the evidence that status requires looks like this:

{
  "name": "advance_ticket",
  "arguments": {
    "ticketId": "TCK-1042",
    "targetStatus": "Review",
    "evidence": {
      "pullRequestUrl": "https://github.com/acme/app/pull/318",
      "lintPassed": true,
      "unitTestsPassed": true
    },
    "idempotencyKey": "adv-1042-review-01"
  }
}

If the evidence satisfies the status's Definition of Done, the transition commits. If it doesn't — say the pull request link is missing — the call returns a clear, structured error explaining which requirement was unmet, rather than a generic failure. The agent can read that message, gather what's missing, and try again.

Workflows & Definition of Done

A workflow defines the statuses a ticket type moves through and the transitions allowed between them. Each status can carry a Definition of Done (DoD) — the specific evidence required before work can leave that status. The DoD does double duty: it guides the agent (it can read the requirements up front) and it gates the transition (the platform refuses to advance the ticket until the requirements are met).

Configuring a workflow

Workflows are configured by an administrator under Ticket Workflows. For each ticket type you define the statuses, the allowed transitions between them, and the Definition of Done for each status. Because the gate is enforced by the platform, it applies equally to human agents and AI agents — there is no way for either to skip a required step.

Example: a software-development workflow

A software-development ticket might move through To Do → In Progress → Review → Testing → Done, with gates like these:

Governance & Safety

The governance rails are always on and are, frankly, the point of the whole feature — they are what make it safe to give an AI agent the ability to change your tickets.

Least privilege per token

An agent's effective access is the intersection of three things: the permissions its persona grants, the tool allowlist on the token, and the tickets it is scoped to. A call is refused unless all three allow it. Narrow any of them and the agent's reach narrows with it.

Dry-run mode

A token (or an individual call) can run in dry-run mode: write and action tools return a preview of what would happen without changing anything. Use it to validate a new agent's behavior before letting it act for real.

Idempotency keys

Any change-making call can carry an idempotency key. If the agent retries the same call — after a network blip, say — RapiDesq recognizes the key and returns the original result instead of applying the change twice. Retries are safe by default.

Human-approval queue

High-impact transitions don't have to be automatic. A workflow can require a transition to wait for human sign-off; the agent's advance_ticket call then enters a pending-approval state, and a person (or a separate agent) approves or rejects it. This is your human-in-the-loop control for the steps that warrant it.

Full audit of every tool call

Every tool call an agent makes is recorded and attributed to that agent's machine-worker identity, and every transition captures the evidence that was supplied. An agent-activity view shows exactly what each agent did and when — the same immutable record you rely on for your human team, extended to your agents.

Outbound webhooks

So agents don't have to poll for work, RapiDesq can send outbound webhooks on events like a ticket being assigned. Your agent wakes on the event, pulls the ticket, and gets to work — more responsive and far more efficient than checking on a timer.

Metering & Cost

Connecting an agent is ordinary authenticated API usage — it does not consume AI credits. RapiDesq runs no language model on the agent's behalf; the agent brings its own intelligence and calls tools, exactly like any API client. Usage is subject to standard rate limits, not AI-credit metering.

The one exception is optional: if you ask the platform to auto-draft a Definition of Done for you using its own managed AI helper, that single convenience is metered in AI credits like any other platform AI feature. Everything else about the agent integration — issuing tokens, listing and calling tools, advancing gated workflows — is free of AI-credit cost.

Getting Started

A first end-to-end run looks like this:

1. Issue a token. In the admin area, create an agent token. Pick the Worker persona for a full working loop (or Read-only to explore safely first), and consider starting in dry-run mode. Copy the token — it is shown only once.
2. Connect the agent. Add the RapiDesq server to your agent's MCP configuration (the .mcp.json above for Claude Code), using your MCP endpoint and the token as a Bearer credential. Confirm the agent can list its tools.
3. Pull and claim a ticket. Have the agent call list_tickets to find work, get_ticket to read the details and the Definition of Done, and claim_ticket to take ownership.
4. Do the work and attach evidence. As the agent progresses, it uses post_update for notes and attach_artifact to record the evidence each gate requires.
5. Advance through the gated workflow. The agent calls advance_ticket with the required evidence to move the ticket to the next status. Where separation of duties or human sign-off applies, the transition waits for an approve_transition call from a different actor. Repeat until the ticket reaches Done.

Once you're confident in the agent's behavior in dry-run, switch the token to live mode and let it work for real.

Best Practices

• Start read-only or dry-run. Give a new agent a Read-only token or a dry-run Worker token first. Watch what it does in the agent-activity view before letting it change anything.
• Grant the narrowest persona that fits. A triage bot doesn't need to advance workflows; a reporting agent doesn't need to write. Match the persona to the job and tighten the scope from there.
• Put the important checks in the Definition of Done. The DoD is enforced for humans and agents alike. Encode "what done means" there rather than relying on any single agent's prompt.
• Use separation of duties for anything you can't undo cheaply. Require human approval, or a second agent, on high-impact transitions.
• Prefer webhooks over polling. Wake your agent on assignment events rather than having it check on a timer.
• Set an expiry and rotate tokens. Give tokens a lifetime and re-issue periodically. Revoke immediately if a token might be exposed.
• Always send an idempotency key on change-making calls. It makes retries safe and prevents accidental double-actions.

Related Topics

• Ticket Management — the ticket lifecycle, statuses, custom fields, and notes that agents read and write.
• AI Bot Configuration — the platform's own managed AI for customer conversations and analysis (distinct from connecting your own agent here).
• Ticket Automation Rules — the platform-run alternative: AI lanes that put a managed AI worker on tickets entering a status, plus deterministic rules, without hosting an agent yourself.
• AI Credits & Billing — how platform AI usage is metered, and why the agent integration itself uses no credits.
• Permissions & Access Control — the permission model that underpins agent token scopes.
• Audit Logs — the immutable record of significant actions, including agent activity.