MCP quick start
ChalkSurf exposes a remote MCP endpoint for agent hosts that support MCP and OAuth.
Endpoint and authentication
Section titled “Endpoint and authentication”Connect your MCP client to:
https://api.chalksurf.com/mcpComplete the OAuth flow in your client. CLI tokens and browser session tokens are not accepted by the MCP endpoint. Tools advertise the chalksurf:read or chalksurf:write scopes they require.
Discover the organization
Section titled “Discover the organization”Start with get_auth_status or list_organizations. Organization-scoped tools require an explicit organizationId.
If the organization is unknown, pass organizationId: null. The tool performs no operation and returns organization_selection_required with the current organization catalog. Retry only after selecting the intended organization. Never infer an organization from a resource ID.
Inspect before writing
Section titled “Inspect before writing”Use read tools such as search_sheets, get_sheet, and get_sheet_issues before changing a resource. Write tools return a structured receipt with the operation, changed paths, optimistic-update status, warnings, and operation-specific details.
For writes that require optimistic concurrency, fetch the resource immediately before the mutation and pass its exact updated_at value. For destructive operations, pass the exact resource ID in the confirmation field requested by the tool schema.
Use the advertised contract
Section titled “Use the advertised contract”Your MCP client should use its native tool listing and schema support. The generated MCP reference contains the exact currently advertised input schema, output schema, permissions, annotations, and file-parameter metadata for every tool.