Home › Guides › MCP or HTTP API: when to use which

MCP or HTTP API: when to use which

AI Tasker publishes two surfaces over the same product: an MCP server with 40 tools and a REST API with an OpenAPI contract of 102 paths. This guide explains what each access solves, when each one is the right choice and why choosing between them is not a pricing decision.

Reviewed · Published

What MCP is for here

MCP is here a discovery and tool surface, not a second product. The AI Tasker MCP server exposes 40 tools over the streamable-http transport at https://mcp.ai-tasker.theboomer.dev/mcp. A client that speaks MCP does not need to know a single REST path: it asks for the catalogue with tools/list, receives every tool with its name, its description and the schema of its arguments, and decides what to call. That is the difference with a classic API: here the contract travels inside the session itself instead of being written into the client beforehand.

Two mechanics matter before the first call. The API key travels in the Authorization: Bearer atkr_… header and is validated against the API before the session opens: with no header, initialize answers 401, and a revoked key answers 401 with INVALID_API_KEY instead of failing later on the first tool call. And initialize returns a session identifier that has to be sent back in the mcp-session-id header of every later call: a request afterwards without a valid session identifier is rejected.

  • The catalogue arrives inside the protocol: 40 tools with name, description and argument schema. The client does not guess paths because there are none.
  • The workspace is resolved by the key: the MCP server takes the workspace that owns the API key, so a read does not need the client to know the identifier.
  • The credential is per request, not per process: one deployed server serves many agents and keys can be rotated without restarting anything.
  • Every request leaves a trace: the usage row records apiKeyId, workspaceId, method, route and channel (human, cli, llm, agent).

What the HTTP API is for here

The HTTP API is a stable REST contract. The OpenAPI document is published at https://api.ai-tasker.theboomer.dev/api/openapi.json with 102 paths, and the browsable documentation is at https://api.ai-tasker.theboomer.dev/docs. There is nothing to discover here: you know the method, the route and the body before you call. The two surfaces are the same product with the same workspace scope: the API key resolves the same workspace in both cases, and a task created through MCP is visible over HTTP and the other way round.

Authentication has one difference worth copying correctly: the API accepts Authorization: Bearer atkr_… or x-api-key: atkr_…, while the MCP endpoint reads the Bearer header and nothing else, because the key is resolved from the request headers and never from the server environment. A client that cannot send HTTP headers on its own cannot speak MCP: that is what the local bridge below is for.

MCP versus the HTTP API: when to use each one

The table does not compare two different products: it compares two ways of reaching the same one. Every row is a real integration situation, and every cell says what that surface can and cannot do.

What each surface solves in AI Tasker: discovery, calls, events, scripting, clients with no MCP support and reading the contract.
SituationMCPHTTP API
Discovering what can be doneThe client asks tools/list and gets the 40 tools with their description and their argument schema. No route needs to be known.There is no discovery: the contract is the OpenAPI document of 102 paths, which you have to read or turn into a client before the first call.
Calling one specific taskA call to the tool (get_task, update_task, move_task) with typed arguments, inside a session that carries its identifier in the mcp-session-id header.A request to the resource route with the API key: GET /api/tasks/{idOrCode}, PUT /api/tasks/{idOrCode} or PATCH /api/tasks/{id}/move. No session, no handshake.
Receiving events without askingThere is no push delivery: MCP is request and response, and the client does not find out about a change until it asks again.There is no push in the REST contract either. Event delivery is the webhook: task.created, task.updated, task.moved and task.archived, signed with HMAC-SHA256.
Scripting a flowIt can be done, with more ceremony: you have to open a session with initialize, keep the session identifier in every call and speak JSON-RPC.This is the natural case: one HTTP request with the Bearer header, no state between calls and a JSON body that is already known.
Integrating with a client that has no MCP supportIt does not work: without MCP support in the client, the protocol cannot be used.It works: any HTTP client will do —curl, fetch, a script in Python— with the API key in the header.
Having a machine read the contractThe catalogue can be audited separately at /llms-full.txt and the manifest at /server.json, but that is a document, not the protocol.The contract is an OpenAPI document at /api/openapi.json, with 102 paths: you can generate a client, validate a mock or read it in a pipeline.

Neither surface reaches further than the other: they are two doors into the same product, with the same hierarchy (workspace, project, task, subtask) and the same scope per workspace. The difference is ergonomics and how well each fits the client you already have, not capability.

The transport: why there is no stdio server to install

AI Tasker publishes the remote streamable-http transport. There is no published stdio package to install in order to get a local MCP server: stdio means the client spawns a process on your machine and talks to it over standard input and output, while what AI Tasker publishes is a remote endpoint that is already deployed, with its own authentication and quota. If your client speaks stdio and nothing else, it needs a local bridge that speaks stdio on your side and forwards the requests to the remote streamable-http endpoint. That bridge is what converts one transport into the other; it is not a different product from AI Tasker.

  • The remote endpoint is what gets published: https://mcp.ai-tasker.theboomer.dev/mcp, with POST /mcp for the calls and GET /health for liveness.
  • The session is mandatory after the handshake: without a valid mcp-session-id, the request is rejected. Clients that speak MCP handle it on their own, and that is why you do not notice it.
  • One key per request, not per process: the same deployed server serves many agents and keys are rotated without restarting.
  • Every client has its own format: Claude Code uses .mcp.json, Cursor uses mcp.json and Codex CLI uses config.toml. The target file and the name of some keys change, the structure does not.

The configuration you can copy

This is the common pattern for a remote MCP server with the streamable-http transport and an API key in the Authorization header. Paste it into the file your client uses and replace the placeholder with the real key, with the atkr_ prefix.

mcpServers configuration for the remote AI Tasker server. The Authorization header is what validates the key.

{
  "mcpServers": {
    "ai-tasker": {
      "type": "http",
      "url": "https://mcp.ai-tasker.theboomer.dev/mcp",
      "headers": {
        "Authorization": "Bearer <AI_TASKER_API_KEY>"
      }
    }
  }
}

And the same thing, without an MCP client, over HTTP. The block below does the three checks that matter before calling an integration good: open the session, list the tools with the session identifier already in the header, and make the equivalent read through the REST API.

The three calls by hand: initialize returns the session identifier, tools/list needs it in the mcp-session-id header, and the third one is the same read through the REST API.

# 1. initialize: returns the mcp-session-id header
curl -i -X POST https://mcp.ai-tasker.theboomer.dev/mcp \
  -H "Authorization: Bearer <AI_TASKER_API_KEY>" \
  -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":"my-cli","version":"1.0.0"}}}'

# 2. tools/list with the session identifier in the header
curl -X POST https://mcp.ai-tasker.theboomer.dev/mcp \
  -H "Authorization: Bearer <AI_TASKER_API_KEY>" \
  -H "mcp-session-id: <MCP_SESSION_ID>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. The same read, through the REST API
curl https://api.ai-tasker.theboomer.dev/api/workspaces \
  -H "Authorization: Bearer <AI_TASKER_API_KEY>"

What each access costs

Quota is charged per operation, not per transport. The catalogue the API publishes at /api/plans says which operations exist and what each one consumes; that is the complete list, and it can be read again live.

Operations and units published by the AI Tasker API (/api/plans).
OperationBucketUnitsWhat it covers
AGENT_READagent1Reading or listing a collection over MCP or the API.
AGENT_MUTATIONagent1Creating, updating, moving or commenting a task from the agent.
AI_SPRINT_PLANhosted_ai1Planning the sprint with hosted AI.
AI_GENERATE_TASKShosted_ai1Generating tasks from natural language.
AI_BREAKDOWNhosted_ai1Breaking a task down into subtasks.
WEBHOOK_DELIVEREDagent0Webhook delivery: not a semantic operation of the agent.
RETRYagent0Retry on 5xx or timeout: a platform failure is not charged.
HUMAN_READhuman0Human read in the dashboard: included.
X402_MCP_PAID_TOOLagent0MCP call paid via x402 (pilot): the payment is outside the quota and the audit record is all that stays here.

The consequence is what settles the debate: the MCP call and the equivalent HTTP call consume the same quota. Reading or listing is AGENT_READ at 1 unit; creating, updating, moving or commenting is AGENT_MUTATION at 1 unit; the three hosted AI operations are 1 unit each; and webhook delivery, retries on platform errors, the human read in the dashboard and the MCP call paid via x402 are 0 units. Choosing MCP or HTTP does not change what you pay: it is an integration decision.

The daily ceiling does not tell the two apart either: dailyAgentOps is 200 authenticated requests with an API key per day, MCP and direct HTTP together, and dailyHostedAiOps is 10 hosted AI operations per day. The free plan gives 1 workspace, 1 human, 2 API keys, 100 agent operations per month, 100 hosted AI operations per month, 3 webhooks and 30 days of activity retention. And the billable unit is 2.00 € per month per approved unit (human member accepted, agent API key created or additional workspace of the owner), with one-off credit packs for consumption.

A cost calculation that does not come from /api/plans is an estimate. The published operation is the one that gets charged, no matter whether the call entered through MCP or through REST.

How to decide: six questions

  • Does the client your agent will talk to have MCP support? If it does not, the question is answered: HTTP API.
  • Is the flow already written in some language and you do not want to touch it? HTTP API: adding a session handshake buys nothing.
  • Does the agent need to discover what it can do, or does it already know? Discover: MCP. Already knows: HTTP.
  • Do you need to find out about a change without asking? Neither of the two: that is a webhook.
  • Is a machine that understands a contract going to read it? OpenAPI: HTTP. A tool catalogue can be read too, but the documented contract is the one of the API.
  • Do you care about the price? It should not matter to you: the quota is the same per operation. If the answer is yes, there is another problem underneath.

What MCP does not solve for you

MCP solves discovery and invocation with typed arguments. Everything else is still your work, and it is worth writing it down so you do not promise capabilities the product does not have.

  • It does not deliver events. Neither MCP nor a REST call announces a change on its own: the events (task.created, task.updated, task.moved, task.archived) arrive by webhook, with the HMAC-SHA256 signature of the body in the x-ai-tasker-signature header.
  • It does not replace the API for a one-off HTTP call from a script. If the flow already exists and works, the MCP session adds state to maintain and nothing else.
  • It does not manage webhooks. Configuring a webhook requires a human session in the dashboard and makes the server POST to a customer URL, so it is not part of the MCP surface.
  • It does not make anything cheaper. The unit is the same per operation and the daily ceiling counts both routes alike.
  • It does not replace the contract for a machine. The contract a machine can read is the OpenAPI document, not a protocol session.

What is left to decide

The question that is left is not which protocol is better, because the answer depends on the client you already have and the flow you already wrote. It is whether you are going to maintain two integrations or one. The guide on MCP for task management has the catalogue of 40 tools and this guide has the contract of 102 paths, and in the middle is the same thing: a workspace with a hierarchy of project, task and subtask. Price does not break the tie either, because the unit is 2.00 € per month per approved unit and consumption is measured per operation, not per protocol. When both surfaces give the same result, pick the one that costs you less to maintain.

How to connect an agent over MCP or over HTTP and check the cost

From the credential to the first tool call over both routes, with the copyable configuration block and the consumption check in the operations table.

  1. Create the API key and choose the route

    In the dashboard, under Settings → API keys, create a key for the workspace and copy the secret with the atkr_ prefix: it is shown once. If the client speaks MCP, the route is MCP; if the flow is your own script, it is the REST API. The same key works for both.

  2. Open the MCP session and discover the tools

    Paste the mcpServers block into the file your client uses and ask for tools/list: 40 tools must show up. The initialize returns a session identifier that has to be sent back in the mcp-session-id header of every later call; without it, the request is rejected.

  3. Do one read and one write over each route

    Over MCP, a read tool (for example list_tasks, which resolves the workspace from the key) and a write one (create_task). Over HTTP, GET /api/workspaces to learn the workspace and GET /api/tasks?workspaceId=<id> for the listing, or POST /api/tasks to create. The result has to be the same over both routes.

  4. Check the consumption and the trail

    Open /api/plans and check which operations were created and how many units each one consumed: reading and listing is AGENT_READ (1 unit) and creating or moving is AGENT_MUTATION (1 unit), while a retry on a platform error is 0 units. Then look at the usage row with method, route and channel to confirm that both routes were recorded.

Frequently asked questions

MCP or the HTTP API: which one should I use?

If the client speaks MCP and the agent is going to discover what it can do, use MCP: the catalogue of 40 tools arrives through the protocol. If the flow is already written, if you need to be told about a change, or if your client has no MCP support, use the REST API with its OpenAPI contract of 102 paths. Price does not decide: both surfaces consume the same quota per operation.

Can I use MCP and the HTTP API at the same time?

Yes, and it is normal: they are the same product with the same workspace scope, so a task created through MCP shows up in the API and the other way round. What you have to watch is the quota, because dailyAgentOps (200 authenticated requests per day) counts both routes alike, and whichever you use more is the one that exhausts the ceiling.

Is there an stdio MCP server I can install?

There is no published stdio package from AI Tasker: what gets published is the remote streamable-http transport at https://mcp.ai-tasker.theboomer.dev/mcp. stdio means the client spawns a process on your machine, so if your client speaks stdio and nothing else, it needs a local bridge that forwards to the remote endpoint. With a client that accepts streamable-http, the mcpServers block of the configuration takes care of the rest.

Sources

Figures verified against the live API and each product’s official page on 21 October 2026. Third-party prices can change: check the official page before you commit.

Related guides

This guide exists to be indexed and cited. It is deliberately not in the menu.