API mcp

This page is for the person who connects a program to the API.

The opt-in remote Model Context Protocol endpoint.

getRootMcpMetadata

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

Read the MCP Protected Resource Metadata.

Discover the canonical MCP resource and its authorization server.

Authentication

No security scheme is declared. See the operation description.

Responses

200

The resource metadata of this installation.

JSON

{
  "description": "The resource metadata of this installation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpMetadata"
      }
    }
  }
}

Schemas: McpMetadata.

400

The request did not match the contract.

JSON

{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

401

The request carries no usable session.

JSON

{
  "description": "The request carries no usable session.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

403

The actor may not perform this operation.

JSON

{
  "description": "The actor may not perform this operation.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

404

The requested resource does not exist.

JSON

{
  "description": "The requested resource does not exist.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

413

The request body is larger than the configured limit. A save of a note adds document_too_large, which means that the update or the document it would produce passes a bound of the workspace. The work stays on the device, which offers recovery rather than sending the same bytes again.

JSON

{
  "description": "The request body is larger than the configured limit. A save of a note adds document_too_large, which means that the update or the document it would produce passes a bound of the workspace. The work stays on the device, which offers recovery rather than sending the same bytes again.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

415

The request media type is not supported.

JSON

{
  "description": "The request media type is not supported.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

429

Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.

JSON

{
  "description": "Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails, UsageLimit.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

503

The service cannot do this work now: it runs as many jobs of this kind as it can, a failure of the service stopped the work, or the object store of the installation took the most writes that one calendar month in UTC allows (record 0193). The code names the cause, for example storage_busy. Nothing changed.

JSON

{
  "description": "The service cannot do this work now: it runs as many jobs of this kind as it can, a failure of the service stopped the work, or the object store of the installation took the most writes that one calendar month in UTC allows (record 0193). The code names the cause, for example storage_busy. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails, UsageLimit.

getMcpMetadata

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

Read the MCP Protected Resource Metadata.

Discover the canonical MCP resource and its authorization server.

Authentication

No security scheme is declared. See the operation description.

Responses

200

The resource metadata of this installation.

JSON

{
  "description": "The resource metadata of this installation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpMetadata"
      }
    }
  }
}

Schemas: McpMetadata.

400

The request did not match the contract.

JSON

{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

401

The request carries no usable session.

JSON

{
  "description": "The request carries no usable session.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

403

The actor may not perform this operation.

JSON

{
  "description": "The actor may not perform this operation.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

404

The requested resource does not exist.

JSON

{
  "description": "The requested resource does not exist.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

413

JSON

{
  "description": "The request body is larger than the configured limit. A save of a note adds document_too_large, which means that the update or the document it would produce passes a bound of the workspace. The work stays on the device, which offers recovery rather than sending the same bytes again.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

415

The request media type is not supported.

JSON

{
  "description": "The request media type is not supported.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

429

JSON

{
  "description": "Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails, UsageLimit.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

503

JSON

{
  "description": "The service cannot do this work now: it runs as many jobs of this kind as it can, a failure of the service stopped the work, or the object store of the installation took the most writes that one calendar month in UTC allows (record 0193). The code names the cause, for example storage_busy. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails, UsageLimit.

serveMcp

POST /mcp

Send a request to the MCP endpoint.

The opt-in stateless MCP endpoint takes an access token of this resource. It answers JSON and opens no event stream. Notifications receive no body.

Authentication

Use one of these options:

mcpAccessToken with scopes notes:read

Request body

JSON

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpMessage"
      }
    }
  }
}

Schemas: McpMessage.

Responses

200

The MCP library answers the request.

JSON

{
  "description": "The MCP library answers the request.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpMessage"
      }
    }
  }
}

Schemas: McpMessage.

202

The notification is accepted. No response body is sent.

JSON

{
  "description": "The notification is accepted. No response body is sent."
}

400

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

401

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OAuthError"
      }
    }
  }
}

Schemas: OAuthError.

403

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/OAuthError"
          },
          {
            "$ref": "#/components/schemas/McpError"
          }
        ]
      }
    }
  }
}

Schemas: McpError, OAuthError.

404

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

405

No event stream or session operation is served.

JSON

{
  "description": "No event stream or session operation is served.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

406

The requested response media type is not supported.

JSON

{
  "description": "The requested response media type is not supported.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

413

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

415

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

429

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

500

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

503

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

openMcp

GET /mcp

Send a request to the MCP endpoint.

The opt-in stateless MCP endpoint takes an access token of this resource. It answers JSON and opens no event stream. Notifications receive no body.

Authentication

Use one of these options:

mcpAccessToken with scopes notes:read

Responses

200

The MCP library answers the request.

JSON

{
  "description": "The MCP library answers the request.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpMessage"
      }
    }
  }
}

Schemas: McpMessage.

202

The notification is accepted. No response body is sent.

JSON

{
  "description": "The notification is accepted. No response body is sent."
}

400

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

401

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OAuthError"
      }
    }
  }
}

Schemas: OAuthError.

403

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/OAuthError"
          },
          {
            "$ref": "#/components/schemas/McpError"
          }
        ]
      }
    }
  }
}

Schemas: McpError, OAuthError.

404

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

405

No event stream or session operation is served.

JSON

{
  "description": "No event stream or session operation is served.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

406

The requested response media type is not supported.

JSON

{
  "description": "The requested response media type is not supported.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

413

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

415

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

429

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

500

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.

503

The protocol request is refused.

JSON

{
  "description": "The protocol request is refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/McpError"
      }
    }
  }
}

Schemas: McpError.