For developers

What this is: the protocol details for your own client or agent. When you need it: you are building on the server rather than using an off-the-shelf client.

Python

import asyncio, os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    headers = {"Authorization": f"Bearer {os.environ['TASKSMATE_TOKEN']}"}
    async with streamablehttp_client("{{MCP_URL}}", headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

asyncio.run(main())

TypeScript

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(new URL("{{MCP_URL}}"), {
  requestInit: { headers: { Authorization: `Bearer ${process.env.TASKSMATE_TOKEN}` } },
});
const client = new Client({ name: "my-agent", version: "0.1.0" });
await client.connect(transport);
console.log((await client.listTools()).tools.map((t) => t.name));

Transport

Streamable HTTP, at one URL for every organization. The stdio packages expose the same tools for local processes.

Signing in

• An access token as a bearer — for your own agents and service accounts. Mint it with the scopes the agent needs; see authentication.
• OAuth 2.1 — for a client that acts for people who sign in: authorization-server metadata for discovery, dynamic client registration, PKCE, and refresh tokens. The consent screen lists the scopes; the token acts as the person who approved it.

finalised at 5.2: The discovery and registration URLs.

Tool annotations

Every tool has a title and a readOnlyHint, and write tools a destructiveHint. Use them to confirm changes with your user; a destructive tool also requires admin. The tools reference lists them.

Rate limits

Tool calls go through the API with your token, so the API’s per-token limits apply — 600 requests a minute for a live token, 60 for a test token. See rate limits.

Errors

A failed tool call returns an error result carrying the API’s problem type and detail, the same problem types as the REST API.

finalised at 5.1: How a problem maps onto an MCP error result.

MCP or the SDK?

The Python SDK calls the REST API: use it when your code decides which calls to make. Use MCP when a model decides.

Acting for your product’s users

A “Connect TasksMate” button in another product — an app that acts for its own users — is a separate, later feature (third-party OAuth apps). Until then, use a service account’s token for server-to-server work.