MCP quick start

ChalkSurf exposes a remote MCP endpoint for agent hosts that support MCP and OAuth.

Endpoint and authentication

Connect your MCP client to:

https://api.chalksurf.com/mcp

Complete the OAuth flow in your client. CLI tokens and browser session tokens are not accepted by the MCP endpoint. Every tool advertises the single chalksurf:mcp resource scope; the editable grant and current organization membership remain the read/write authority.

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

Use read tools such as search_sheets, get_sheet, and get_sheet_issues before changing a resource. The core exercise, sheet, and folder search/list/get tools return their primary results with a top-level resources array of absolute browser links, repeated in ordinary text content so clients can include them in conversation. get_exercise_usage links the sheets in its usage result. Nested matching sources, embedded exercises, versions, issues, and metadata are not linked. Empty primary results return resources: [] without an extra link block.

Write tools return a structured receipt with the operation, changed paths, optimistic-update status, warnings, and operation-specific details.

Successful writes to a surviving exercise, sheet, or folder also return an absolute browser link in receipt.resource.url and ordinary text content. Completed jobs returned by list_jobs, get_job, or wait_for_jobs expose every resulting exercise or sheet in resources. These links include the selected organization as a navigation hint; ChalkSurf switches only after the signed-in user’s memberships resolve, and normal server authorization remains authoritative. Delete receipts and the legacy singular bulk-sheet receipt are intentionally not linked.

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

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.