Hosted MCP Endpoint

The hosted MCP endpoint lets any MCP-compatible AI client connect to MarkDocket over HTTPS using OAuth 2.1. You do not need to install anything locally — the endpoint is served directly by the MarkDocket API at /mcp and speaks the Streamable HTTP transport defined by the MCP specification.

Endpoint URL

The hosted MCP endpoint is available at:

https://api.markdocket.com/mcp

All communication uses the MCP Streamable HTTP transport. Point your MCP client at this URL and follow the OAuth discovery flow described in the next section.

Authentication: OAuth 2.1

The hosted MCP endpoint requires an OAuth 2.1 access token. It does not accept personal API keys or session cookies directly — those credential types are bound to different API surfaces.

Discovery

The authorization server metadata is published at:

https://api.markdocket.com/.well-known/oauth-authorization-server

MCP clients that implement OAuth 2.1 discovery (including the MarkDocket CLI in browser-login mode) read the authorization_endpoint, token_endpoint, and registration_endpoint from this document automatically.

Dynamic client registration

The server supports dynamic client registration (RFC 7591). MCP clients that register dynamically will receive a client_id scoped to that session's redirect URI. You do not need to obtain or embed a static client_id in advance.

If your client supports it, PKCE with the S256 method is required.

Consent page

After the user authenticates, they are shown an OAuth consent page that lists the permissions the connecting client is requesting. Users can deselect optional scopes before granting access.

The consent page explicitly discloses that the following capabilities are excluded from all MCP access tokens regardless of what scopes are requested:

• Billing changes — adding or removing payment methods, changing plans, or viewing full billing history
• Device pairing — registering or removing MarkDocket Desktop companion devices
• Credential changes — updating passwords, two-factor authentication settings, or connected account integrations

These exclusions are enforced server-side. No OAuth access token, regardless of scope, can perform billing mutations, device management, or credential operations.

The openid scope is always included and cannot be deselected.

How tokens are scoped

OAuth access tokens issued for the hosted MCP endpoint are resource-bound to that endpoint. They cannot be used to call MarkDocket's general /api/* routes directly.

All tool calls made with an OAuth access token flow through the /mcp endpoint, which applies a server-side provenance check before dispatching to the underlying API. This means:

• Only tools that appear in the published tool catalog are reachable via MCP tokens.
• Any internal API route that is not part of the catalog remains permanently unreachable from an MCP token, even if the URL is known.
• New catalog tools become available automatically without any change to the token or the OAuth grant.

This architecture is the same for both the hosted MCP endpoint (OAuth 2.1 tokens) and the /v1/tools REST gateway (personal API keys).

Tool availability

The tool catalog served by the hosted MCP endpoint is derived from the same canonical registry used by the CLI, the stdio MCP server, and the /v1/tools REST gateway. In practice, the tool surface is identical across all four surfaces with one exception.

Agent-only tools are excluded

A small set of tools used by MarkDocket's internal AI agent are not exposed through any external surface — hosted MCP, stdio MCP, or the REST gateway. These tools depend on privileged internal state (such as an active agent session or platform AI gateway credentials) that is not available to external callers.

The exclusion list is applied at the catalog level, so these tools never appear in tool listings, are never callable, and produce no visible error — they simply do not exist from the perspective of an MCP client.

MCP tool annotations

Every tool in the catalog carries MCP behavioral annotations:

These hints are derived automatically from each tool's HTTP method and name — they are not maintained as a separate list. An AI client can use them to decide whether to confirm an action before calling.

Using the MarkDocket CLI with browser OAuth

The markdocket login command authenticates via browser OAuth and then routes all tool calls through the hosted MCP endpoint using the resulting access token. This is the recommended way to use the CLI when you do not have a personal API key.

markdocket login

The command:

1. Discovers the authorization server at /.well-known/oauth-authorization-server.
2. Dynamically registers a public OAuth 2.1 client with a loopback redirect URI.
3. Opens your browser to the authorization and consent page.
4. Exchanges the authorization code for an access token using PKCE.
5. Stores the token locally and routes subsequent tool calls through the /mcp endpoint.

After login, all markdocket call <tool> commands use the hosted MCP endpoint rather than calling the API directly.

Connecting a third-party MCP client

Any MCP client that supports OAuth 2.1 and the Streamable HTTP transport can connect to the hosted endpoint. The general steps are:

1. Configure the client's MCP server URL to https://api.markdocket.com/mcp.
2. Allow the client to perform OAuth discovery and dynamic client registration automatically, or pre-configure the authorization_endpoint and token_endpoint from the well-known metadata document.
3. Complete the browser-based authorization and consent flow when prompted.
4. The client receives a resource-bound access token and can begin calling tools.

Consult your MCP client's documentation for the exact configuration fields. Most clients that support the MCP Streamable HTTP transport handle OAuth discovery automatically.

Billing and usage

Tool calls made through the hosted MCP endpoint are metered against your MarkDocket account in the same way as tool calls made from the CLI or the web application. If a tool call would exceed your plan limits, the endpoint returns a structured billing error instead of executing the tool.

An MCP client that encounters a billing error will receive an isError: true response with a structured structuredContent field describing the required action (for example, adding a payment method or upgrading your plan). The specific action required depends on the reason for the block.

Comparing hosted MCP and stdio MCP