Browse all guides
All guides
MCP

MCP HTTP and OAuth reference

Reference for Tartol’s public MCP transport and OAuth endpoints, with request examples.

14 min readUpdated August 27, 2026

Quick visual guide

Use the documented MCP URL and OAuth flow exactly as shown.

  1. 1

    Check the base URL

    Open the MCP reference and use the published HTTPS server URL.

    MCP documentation overviewMCP guide
  2. 2

    Copy the server URL

    Settings > Integrations shows the server URL for each supported client.

    MCP server URL in Settings IntegrationsCopy server URL
  3. 3

    Follow OAuth in order

    Use discovery, authorization, token exchange, and revocation sections without skipping required checks.

    MCP guide contents navigationFollow the sections

Red labels show the exact control to use.

Detailed referenceOpen this for definitions, limits, examples, and troubleshooting.

Base URL and authentication

All public endpoints use https://tartol.com. Compatible clients discover Tartol’s OAuth endpoints, open the browser authorization flow, and send the resulting access token when calling the MCP endpoint.

Remote MCP server URL
https://tartol.com/api/mcp

Public endpoints

MethodPathPurpose
GET/.well-known/oauth-protected-resourceMCP resource and supported scopes.
GET/.well-known/oauth-authorization-serverOAuth server metadata and endpoint URLs.
GET/oauth/authorizeStart authorization code flow with PKCE.
POST/oauth/registerRegister a public OAuth client.
POST/oauth/tokenExchange a code or refresh token.
POST/oauth/revokeRevoke an OAuth token.
GET, POST, DELETE/api/mcpStreamable HTTP MCP transport.
OPTIONS/api/mcpBrowser CORS preflight.

MCP transport

POST/api/mcp

Use POST for MCP messages. GET and DELETE support the Streamable HTTP connection lifecycle. Compatible MCP clients manage these methods for you.

RequirementValue
Content typeapplication/json for POST requests
Accepted response typesapplication/json, text/event-stream
Maximum POST body512 KiB
Authenticated POST limit120 requests per minute per connection and client
Action limit20 requests per minute and 2,000 per day per connection

Call an MCP tool

These raw examples call whoami with an OAuth access token. Use an MCP SDK or compatible client for production integrations so authorization and protocol negotiation stay current.

curl https://tartol.com/api/mcp \
  -X POST \
  -H "Authorization: Bearer $TARTOL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "MCP-Method: tools/call" \
  -H "MCP-Name: whoami" \
  --data '{
    "jsonrpc": "2.0",
    "id": "whoami-1",
    "method": "tools/call",
    "params": {
      "name": "whoami",
      "arguments": {},
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": {"name": "my-client", "version": "1.0.0"},
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

OAuth discovery metadata

GET/.well-known/oauth-protected-resource

Read the protected-resource document first. It identifies the MCP resource, authorization server, and supported scopes. Then read /.well-known/oauth-authorization-server for the OAuth endpoint URLs and supported flow.

cURL
curl https://tartol.com/.well-known/oauth-protected-resource
curl https://tartol.com/.well-known/oauth-authorization-server

Register an OAuth client

POST/oauth/register

Register public clients only. redirect_uris is required. The default grant is authorization_code; add refresh_token when the client needs long-lived access.

cURL
curl https://tartol.com/oauth/register \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "client_name": "My Tartol client",
    "redirect_uris": ["https://client.example.com/oauth/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "scope": "tartol:read",
    "token_endpoint_auth_method": "none"
  }'
FieldRequiredNotes
redirect_urisYesArray of HTTPS URIs, or valid loopback HTTP URIs for native clients.
client_nameNoName shown during authorization.
scopeNoSpace-delimited Tartol scopes.
grant_typesNoauthorization_code, with optional refresh_token.
response_typesNoMust be ["code"] when supplied.
token_endpoint_auth_methodNoMust be none.

Request authorization

GET/oauth/authorize

Redirect the user to this endpoint. PKCE with S256 is required. After approval, Tartol returns code, state, and iss to the registered redirect URI.

Query parameterRequiredValue
client_idYesClient ID returned by registration.
redirect_uriYesAn exact registered URI.
response_typeYescode
code_challengeYesBase64url SHA-256 PKCE challenge.
code_challenge_methodYesS256
resourceYeshttps://tartol.com/api/mcp
scopeNoSpace-delimited requested scopes.
stateRecommendedRandom value validated by the client.
response_modeNoquery

Exchange or refresh a token

POST/oauth/token

Send application/x-www-form-urlencoded data. Public clients send client_id in the form body and do not use HTTP Basic authentication.

Exchange an authorization code
curl https://tartol.com/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=$TARTOL_CLIENT_ID" \
  --data-urlencode "code=$TARTOL_AUTH_CODE" \
  --data-urlencode "redirect_uri=https://client.example.com/oauth/callback" \
  --data-urlencode "code_verifier=$TARTOL_CODE_VERIFIER" \
  --data-urlencode "resource=https://tartol.com/api/mcp"
Refresh an access token
curl https://tartol.com/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=$TARTOL_CLIENT_ID" \
  --data-urlencode "refresh_token=$TARTOL_REFRESH_TOKEN" \
  --data-urlencode "resource=https://tartol.com/api/mcp"

Revoke a token

POST/oauth/revoke

Send the client ID and token as form data. A successful request returns 200 with an empty body.

cURL
curl https://tartol.com/oauth/revoke \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=$TARTOL_CLIENT_ID" \
  --data-urlencode "token=$TARTOL_ACCESS_TOKEN"

HTTP errors

StatusMeaning
400Invalid request, OAuth parameter, or MCP message.
401Missing, invalid, expired, or revoked credential.
403Origin not allowed.
413MCP POST body exceeds 512 KiB.
415MCP POST is not application/json.
429Rate limit reached. Follow Retry-After when present.
503Authentication, OAuth storage, or MCP service is temporarily unavailable.

Keep learning

REST API overviewRead guide MCP tool referenceRead guide OAuth reference for MCP clientsRead guide

Still need help?

Tell us what you were trying to do and what happened.

Contact support
Last updated August 27, 2026