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.
https://app.agent-task.com/v1/public/mcpOne 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.
- 1Open Claude → Settings → Connectors (Claude.ai) or Settings → Developer (Claude Desktop).
- 2Choose “Add custom connector” / “Add MCP server”.
- 3Paste the MCP server URL above as the server endpoint.
- 4Authenticate when prompted — sign in via OAuth, or supply an organization API key (amk_…).
- 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.
- 1In Claude Code, add the plugin marketplace with the command below.
- 2Run /plugin install agent-task@agent-task.
- 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_…" }.
- 4Fully quit and relaunch Claude Code — the MCP server connects at startup, so the key must be set before launch.
- 5Run /mcp to confirm agent-task is connected, then type /start, /update, or /finish to confirm it works.
/plugin marketplace add alireza1220/agent-task-plugin
/plugin install agent-task@agent-taskThe 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.
- 1Create or open .cursor/mcp.json in your project (or the global ~/.cursor/mcp.json).
- 2Add an entry for AgentTask using the snippet below.
- 3Replace YOUR_API_KEY with an organization API key (amk_…).
- 4Reload Cursor; AgentTask’s tools appear in the MCP tool list.
{
"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.
- 1Open the connector / MCP settings in your ChatGPT or OpenAI client.
- 2Add a new MCP server and paste the MCP server URL above.
- 3Provide an organization API key (amk_…) for authorization.
- 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.
- 1Update the marketplace so Claude Code sees the newest plugin version:
- 2Reinstall (or update) the plugin from the refreshed marketplace:
- 3Make sure ~/.claude/settings.json has the plugin enabled, the marketplace registered, and your API key set (sample below).
- 4Fully quit and relaunch Claude Code — the MCP server connects at startup, so settings must be in place before launch.
- 5Run /mcp to confirm agent-task is connected, then try /start, /update, or /finish.
/plugin marketplace update agent-task
/plugin install agent-task@agent-task{
"enabledPlugins": ["agent-task@agent-task"],
"extraKnownMarketplaces": {
"agent-task": {
"source": { "source": "github", "repo": "alireza1220/Agent_task_management" }
}
},
"env": {
"AGENT_TASK_API_KEY": "amk_xxxxxxxxxxxxxxxxxxxxxxxx"
}
}jq '{enabledPlugins, marketplaces: (.extraKnownMarketplaces | keys), apiKey: ((.env.AGENT_TASK_API_KEY // "")[0:8] + "…")}' ~/.claude/settings.jsonConfirm + 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
5list_tasks_and_subtasksList tasks and their subtasks together — each typed, with subtask parent refs. Cursor-paginated.
create_taskCreate one task — or a batch of up to 50 — with group, assignee, and labels. Auto-suggests a group when none is given.
update_taskUpdate any fields (status, priority, assignee, labels, dates…) on one task or a batch.
suggest_groupRecommend the best group for a new task from each group’s learned memory.
start_workResume your in-flight ticket or claim the next one — creating it only when needed.
Search & fetch
2searchFull-text search across tasks, projects, and notes, grouped by type.
fetchFetch any entity by app URL or UUID — task, project, note, group, label, or attachment.
Subtasks
3list_subtasksList the subtasks of a task.
create_subtaskAdd a subtask under a parent task.
update_subtaskUpdate a subtask’s title, description, status, or assignee.
Projects
3list_projectsList the projects (initiatives) in a space.
create_projectCreate a new project (initiative) in a space.
update_projectUpdate a project’s name, status, priority, health, dates, or lead.
Task groups
3list_task_groupsList the task groups (workflow sections) in a space.
create_task_groupCreate a workflow section, with a description used for auto-routing.
update_task_groupRename a group or set its description and sprint dates.
Comments
4list_commentsList the comments on a task or subtask.
add_commentAdd a comment to a task or subtask.
update_commentEdit a comment.
delete_commentDelete a comment.
Labels
3list_labelsList a space’s color-coded labels.
create_labelCreate a color-coded label.
update_labelRename a label or change its color.
Notes · OAuth
3list_notesList notes you can access. Requires a user (OAuth) token.
create_noteCreate a note in a space (OAuth).
update_noteUpdate a note with optimistic version locking (OAuth).
Spaces & members
2list_spacesList the spaces (workspaces) in your organization.
list_space_membersList members to resolve assignees by name or id.
Attachments & agents
6list_attachmentsList a task, subtask, or project’s attachments with download URLs.
download_attachmentsDownload all of a target’s attachments as a single ZIP.
prepare_attachment_uploadGet a signed PUT url for a direct upload (allow-listed types).
create_attachment_from_uploadFinalize an uploaded file as an attachment (type + bytes verified).
delete_attachmentDelete a task, subtask, or project attachment.
update_task_claimReport 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
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"}}}'# 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"}'# ✗ 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/403npx @modelcontextprotocol/inspector \
--cli https://app.agent-task.com/v1/public/mcp \
--transport http \
--header "Authorization: Bearer amk_xxxxxxxxxxxxxxxxxxxxxxxx"{
"mcpServers": {
"agent-task": {
"url": "https://app.agent-task.com/v1/public/mcp",
"headers": { "Authorization": "Bearer amk_xxxxxxxxxxxxxxxxxxxxxxxx" }
}
}
}# 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.{
"servers": {
"agent-task": {
"type": "http",
"url": "https://app.agent-task.com/v1/public/mcp",
"headers": { "Authorization": "Bearer amk_xxxxxxxxxxxxxxxxxxxxxxxx" }
}
}
}# 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.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());# 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
| Symptom | Cause | Fix |
|---|---|---|
| 401 Unauthorized | Missing/malformed Authorization header, or not an org amk_ key. | 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. | Use a key whose org grants the action; check your plan/permissions. |
| 406 / no response body | Missing Accept header on a streaming response. | Add `Accept: application/json, text/event-stream`. |
| Client shows “no tools” | initialize didn’t complete or the transport is wrong. | 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. | Confirm the header block in the client’s mcp.json; restart the client after editing. |
| OAuth loop / consent fails | Client cached stale metadata. | 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.