MCP

MCP Server Description

GET /.well-known/mcp.json

Same document as a plain GET /mcp.

Authentication: None.

Response

200 How to connect (application/json)

Errors

Example

curl "https://mcp.machinemail.dev/.well-known/mcp.json"

{
  "name": "Production",
  "version": "string",
  "transport": "streamable-http",
  "url": "https://example.com/webhooks/machinemail",
  "authentication": {
    "type": "bearer",
    "header": "string",
    "resource_metadata": "string",
    "oauth": {
      "authorization_server": "string",
      "resource": "string"
    }
  },
  "docs": "string"
}

MCP Description or Stream

GET /mcp

Without Accept: text/event-stream (a browser, for example): the server description, no authentication. With it, this would be the standalone MCP server-to-client stream; the server is stateless and has none, so an authenticated request answers 405 (use POST) and an unauthenticated one 401 with the WWW-Authenticate challenge. HEAD needs a valid token whatever the Accept (401 with the challenge otherwise), so clients can probe for the challenge.

Authentication: None.

Response

200 The server description (application/json)

Errors

Example

curl "https://mcp.machinemail.dev/mcp"

{
  "name": "Production",
  "version": "string",
  "transport": "streamable-http",
  "url": "https://example.com/webhooks/machinemail",
  "authentication": {
    "type": "bearer",
    "header": "string",
    "resource_metadata": "string",
    "oauth": {
      "authorization_server": "string",
      "resource": "string"
    }
  },
  "docs": "string"
}

MCP JSON-RPC (Streamable HTTP)

POST /mcp

MachineMail as a remote MCP server over Streamable HTTP, stateless: send one JSON-RPC message per request with Authorization: Bearer set to an API key, an OAuth access token for the MCP server (aud https://mcp.machinemail.dev/mcp, <PUBLIC_URL>/mcp or <PUBLIC_URL>/) or an auth.md access token (the session cookie is not accepted). Every request is served independently; there is no Mcp-Session-Id.

The canonical URL is https://mcp.machinemail.dev/mcp (MACHINEMAIL_MCP_URL on self-hosted servers); <PUBLIC_URL>/mcp (https://machinemail.dev/mcp) is the same server, kept as a legacy alias.

Without a valid token the answer is 401 with WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource/mcp", scope="..." on the host the request came to (plus error="invalid_token" when a token was sent): MCP clients follow it to the authorization server and sign the person in with OAuth (authorization code with PKCE).

Protocol 2026-07-28 (per-request _meta, server/discover), with stateless fallback for 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05 clients (initialize). The tools act with the credential’s scope and permissions. Bodies over 2 MiB are rejected.

Responses are JSON, or text/event-stream when the client accepts it; protocol-level errors are JSON-RPC error objects with an HTTP 4xx status. See the MCP specification for the methods.

Authentication: Authorization: Bearer <api key>.

Request body

Content type: application/json. Required.

Type: unknown

Response

200 JSON-RPC response (application/json, text/event-stream)

Type: Record<string, unknown>

202 Notification or response accepted (empty body)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://mcp.machinemail.dev/mcp" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "key": "value"
}

MCP Session Termination (Unsupported)

DELETE /mcp

The server keeps no sessions, so there is nothing to delete: always 405 for an authenticated caller.

Authentication: Authorization: Bearer <api key>.

Response

Errors

Error bodies use the error envelope.

Example

curl -X DELETE "https://mcp.machinemail.dev/mcp" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"