Skip to content

Portable MCP

AgentTask exposes a single remote MCP endpoint — one HTTPS URL, no local install, no per-machine setup. Point any MCP client (or plain HTTP) at it, authenticate with an organization API key or OAuth 2.1, and your agents can read and write the same backlog.

Endpoint
https://app.agent-task.com/v1/public/mcp

One HTTPS URL. No local install.

Authentication

Bearer API key

Create an organization key (amk_…) in Settings → API keys and send it as a Bearer token. Simplest to set up — best for servers, scripts, and headless agents.

OAuth 2.1

For user-delegated access, the endpoint advertises OAuth 2.1 discovery metadata at /.well-known/oauth-authorization-server. MCP clients that support OAuth can connect with just the endpoint URL and complete the auth flow in-app.

Connect your client

AgentTask speaks the Model Context Protocol (MCP) — the open standard for giving AI tools access to your systems. Add one server URL to Claude, Cursor, ChatGPT, or any MCP client, and your agents can read and manage tasks, projects, and notes directly in the conversation.

Claude (Anthropic)

Add AgentTask as a custom connector in Claude.ai or Claude Desktop to manage your backlog in chat.

  1. 1Open Claude → Settings → Connectors (Claude.ai) or Settings → Developer (Claude Desktop).
  2. 2Choose “Add custom connector” / “Add MCP server”.
  3. 3Paste the MCP server URL above as the server endpoint.
  4. 4Authenticate when prompted — sign in via OAuth, or supply an organization API key (amk_…).
  5. 5Start a chat and ask Claude to list your spaces or create a task to confirm the connection.

This is different from the Claude Code plugin below. The custom connector wires up the MCP tools only — it does not install the /start…/finish slash commands or the workflow skills. In Claude.ai / Claude Desktop, add the skills manually (Settings → Capabilities → Skills) if you want the guided workflows; the one-step plugin install is Claude Code only.

Claude Code (plugin)

Install the AgentTask plugin in Claude Code to get the MCP tools plus intent-level slash commands — /start, /update, /report, /organize, /init, and /finish — that drive your backlog for you.

  1. 1In Claude Code, add the plugin marketplace with the command below.
  2. 2Run /plugin install agent-task@agent-task.
  3. 3Set your organization API key (amk_…) so the MCP can authenticate: add an "env" block to ~/.claude/settings.json — "env": { "AGENT_TASK_API_KEY": "amk_…" }.
  4. 4Fully quit and relaunch Claude Code — the MCP server connects at startup, so the key must be set before launch.
  5. 5Run /mcp to confirm agent-task is connected, then type /start, /update, or /finish to confirm it works.
Claude Code
/plugin marketplace add alireza1220/agent-task-plugin
/plugin install agent-task@agent-task

The plugin is self-contained and can also be shared as a standalone repo or a local folder — it ships no secrets, so it is safe to distribute publicly. Unlike a plain MCP connector (which provides the tools only), the plugin also bundles the slash commands and workflow skills.

Cursor

Register the MCP server in Cursor’s config so the agent can act on your tasks while you code.

  1. 1Create or open .cursor/mcp.json in your project (or the global ~/.cursor/mcp.json).
  2. 2Add an entry for AgentTask using the snippet below.
  3. 3Replace YOUR_API_KEY with an organization API key (amk_…).
  4. 4Reload Cursor; AgentTask’s tools appear in the MCP tool list.
.cursor/mcp.json
{
  "mcpServers": {
    "agent-task": {
      "url": "https://app.agent-task.com/v1/public/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

ChatGPT / OpenAI

Reach AgentTask from ChatGPT or the OpenAI tooling through their MCP-compatible connector support.

  1. 1Open the connector / MCP settings in your ChatGPT or OpenAI client.
  2. 2Add a new MCP server and paste the MCP server URL above.
  3. 3Provide an organization API key (amk_…) for authorization.
  4. 4Confirm the AgentTask tools are listed, then ask it to read or create a task.

MCP support across ChatGPT/OpenAI surfaces is still rolling out and varies by plan and client. If a native MCP connector isn’t available to you yet, any MCP-compatible bridge can connect to the same server URL.

Updating the AgentTask plugin

Already installed the plugin? Here’s how to pull the latest version, confirm your settings, and verify the connection.

  1. 1Update the marketplace so Claude Code sees the newest plugin version:
  2. 2Reinstall (or update) the plugin from the refreshed marketplace:
  3. 3Make sure ~/.claude/settings.json has the plugin enabled, the marketplace registered, and your API key set (sample below).
  4. 4Fully quit and relaunch Claude Code — the MCP server connects at startup, so settings must be in place before launch.
  5. 5Run /mcp to confirm agent-task is connected, then try /start, /update, or /finish.
Update + reinstall (Claude Code)
/plugin marketplace update agent-task
/plugin install agent-task@agent-task
~/.claude/settings.json (sample)
{
  "enabledPlugins": ["agent-task@agent-task"],
  "extraKnownMarketplaces": {
    "agent-task": {
      "source": { "source": "github", "repo": "alireza1220/Agent_task_management" }
    }
  },
  "env": {
    "AGENT_TASK_API_KEY": "amk_xxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
Verify your settings with jq (masks the key)
jq '{enabledPlugins, marketplaces: (.extraKnownMarketplaces | keys), apiKey: ((.env.AGENT_TASK_API_KEY // "")[0:8] + "…")}' ~/.claude/settings.json

Confirm + use

  • Run /mcp — agent-task should appear as connected.
  • Run /start to begin a task, /update to sync progress, or /finish to close it out.

The plugin is self-contained — it points at the hosted MCP endpoint and ships no secrets. If /mcp doesn’t list agent-task after relaunch, re-check the API key in settings.json and that the plugin is enabled.

What the MCP server exposes

Grouped by resource. Tool names are stable identifiers you call from your agent; descriptions summarize what each does.

Tasks

5
  • list_tasks_and_subtasks

    List tasks and their subtasks together — each typed, with subtask parent refs. Cursor-paginated.

  • create_task

    Create one task — or a batch of up to 50 — with group, assignee, and labels. Auto-suggests a group when none is given.

  • update_task

    Update any fields (status, priority, assignee, labels, dates…) on one task or a batch.

  • suggest_group

    Recommend the best group for a new task from each group’s learned memory.

  • start_work

    Resume your in-flight ticket or claim the next one — creating it only when needed.

Search & fetch

2
  • search

    Full-text search across tasks, projects, and notes, grouped by type.

  • fetch

    Fetch any entity by app URL or UUID — task, project, note, group, label, or attachment.

Subtasks

3
  • list_subtasks

    List the subtasks of a task.

  • create_subtask

    Add a subtask under a parent task.

  • update_subtask

    Update a subtask’s title, description, status, or assignee.

Projects

3
  • list_projects

    List the projects (initiatives) in a space.

  • create_project

    Create a new project (initiative) in a space.

  • update_project

    Update a project’s name, status, priority, health, dates, or lead.

Task groups

3
  • list_task_groups

    List the task groups (workflow sections) in a space.

  • create_task_group

    Create a workflow section, with a description used for auto-routing.

  • update_task_group

    Rename a group or set its description and sprint dates.

Comments

4
  • list_comments

    List the comments on a task or subtask.

  • add_comment

    Add a comment to a task or subtask.

  • update_comment

    Edit a comment.

  • delete_comment

    Delete a comment.

Labels

3
  • list_labels

    List a space’s color-coded labels.

  • create_label

    Create a color-coded label.

  • update_label

    Rename a label or change its color.

Notes · OAuth

3
  • list_notes

    List notes you can access. Requires a user (OAuth) token.

  • create_note

    Create a note in a space (OAuth).

  • update_note

    Update a note with optimistic version locking (OAuth).

Spaces & members

2
  • list_spaces

    List the spaces (workspaces) in your organization.

  • list_space_members

    List members to resolve assignees by name or id.

Attachments & agents

6
  • list_attachments

    List a task, subtask, or project’s attachments with download URLs.

  • download_attachments

    Download all of a target’s attachments as a single ZIP.

  • prepare_attachment_upload

    Get a signed PUT url for a direct upload (allow-listed types).

  • create_attachment_from_upload

    Finalize an uploaded file as an attachment (type + bytes verified).

  • delete_attachment

    Delete a task, subtask, or project attachment.

  • update_task_claim

    Report agent progress: in_progress, blocked, completed, or failed.

The exact tool set is governed by the product instance and may evolve; your client’s tools/list call is always the authoritative, current source of truth.

Worked examples

1. Initialize (curl)
curl -X POST https://app.agent-task.com/v1/public/mcp \
  -H "Authorization: Bearer amk_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
       "clientInfo":{"name":"curl","version":"1.0"}}}'
2a. Correct Bearer (works)
# Header format matters: "Bearer " then the amk_ key, no quotes.
curl -X POST https://app.agent-task.com/v1/public/mcp \
  -H "Authorization: Bearer amk_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
2b. Wrong Bearer (401 — common mistakes)
# ✗ missing "Bearer " prefix      → 401
curl ... -H "Authorization: amk_xxxxxxxxxxxxxxxxxxxxxxxx"
# ✗ quoting the value             → 401
curl ... -H 'Authorization: Bearer "amk_xxxxxxxxxxxxxxxxxxxxxxxx"'
# ✗ using a personal token, not an org amk_ key → 401/403
3. MCP Inspector (CLI)
npx @modelcontextprotocol/inspector \
  --cli https://app.agent-task.com/v1/public/mcp \
  --transport http \
  --header "Authorization: Bearer amk_xxxxxxxxxxxxxxxxxxxxxxxx"
4. Cursor (~/.cursor/mcp.json)
{
  "mcpServers": {
    "agent-task": {
      "url": "https://app.agent-task.com/v1/public/mcp",
      "headers": { "Authorization": "Bearer amk_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}
5. Claude Code / Claude Desktop
# Claude Code (CLI): add the remote HTTP MCP server
claude mcp add --transport http agent-task https://app.agent-task.com/v1/public/mcp \
  --header "Authorization: Bearer amk_xxxxxxxxxxxxxxxxxxxxxxxx"

# Claude Desktop: Settings → Connectors → Add custom connector → paste the URL,
# then add the Authorization header with your amk_ key.
6. VS Code / Windsurf (.vscode/mcp.json)
{
  "servers": {
    "agent-task": {
      "type": "http",
      "url": "https://app.agent-task.com/v1/public/mcp",
      "headers": { "Authorization": "Bearer amk_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}
7. OAuth 2.1 (no static key)
# Clients that support OAuth 2.1 need only the endpoint URL — they discover auth at:
#   https://app.agent-task.com/.well-known/oauth-authorization-server
# Add the server by URL and approve the in-app consent screen; no amk_ key required.
8. Node SDK (@modelcontextprotocol/sdk)
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(new URL("https://app.agent-task.com/v1/public/mcp"), {
  requestInit: { headers: { Authorization: `Bearer ${process.env.AGENT_TASK_API_KEY}` } },
});
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);
console.log(await client.listTools());
9. Key as an environment variable
# Keep the key out of configs and source control:
export AGENT_TASK_API_KEY="amk_xxxxxxxxxxxxxxxxxxxxxxxx"
curl -X POST https://app.agent-task.com/v1/public/mcp \
  -H "Authorization: Bearer $AGENT_TASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/list"}'

Troubleshooting

401 Unauthorized
Missing/malformed Authorization header, or not an org amk_ key.
Fix: Send `Authorization: Bearer amk_…` (with the space, no quotes). Use an organization API key, not a personal token.
403 Forbidden
The key’s organization/role can’t perform the action.
Fix: Use a key whose org grants the action; check your plan/permissions.
406 / no response body
Missing Accept header on a streaming response.
Fix: Add `Accept: application/json, text/event-stream`.
Client shows “no tools”
initialize didn’t complete or the transport is wrong.
Fix: Use the HTTP (Streamable) transport and the exact endpoint URL; run `tools/list` after `initialize`.
Works in curl, not in the client
Client config header not applied.
Fix: Confirm the header block in the client’s mcp.json; restart the client after editing.
OAuth loop / consent fails
Client cached stale metadata.
Fix: Remove and re-add the server; ensure the client supports OAuth 2.1 discovery.

Cloud vs self-hosted

On AgentTask Cloud the endpoint is hosted for you at the URL above — nothing to install. Self-hosted/enterprise deployments expose the same MCP endpoint on your own host (e.g. https://agenttask.your-company.com/v1/public/mcp); the examples are identical apart from the hostname.

See the enterprise self-hosting page →

Ready to connect?

Create an organization API key and point your client at the endpoint.

Get your API key