Skip to main content
Artifacts exposes an MCP server at /mcp. MCP clients can authenticate, discover tools, and call the same domain services used by the REST API and CLI.
This page covers connecting and using MCP. For every tool and its input schema, see the MCP reference.

​
Endpoint

When running locally: 
http://localhost:3000/mcp
The Next.js app rewrites /mcp to the Hono API, so MCP clients use the same public origin as browser OAuth.

​
Discovery metadata

http://localhost:3000/.well-known/oauth-protected-resource
http://localhost:3000/.well-known/oauth-authorization-server
The protected resource document advertises:
  • Resource: PUBLIC_APP_URL
  • Authorization server: BETTER_AUTH_URL
  • Supported scopes: openid, profile, email
  • Bearer method: header

​
How a client connects

MCP auth is powered by Better Auth’s MCP plugin:
1

Discover metadata

The client fetches the protected resource metadata.
2

Register

The client dynamically registers, if it supports dynamic registration.
3

Consent

The user completes browser consent and Google sign-in.
4

Exchange a token

The client exchanges the authorization code for a bearer token.
5

Call tools

The client calls /mcp with authorization: Bearer ....

​
Tools

Every tool takes structured JSON and returns domain objects, validated with the same Zod schemas as the REST and CLI paths. 
get_current_principal    list_workspaces          list_projects
create_project           create_artifact          update_artifact
restore_artifact_version get_artifact             get_artifact_content
list_artifact_versions   diff_artifact_versions   get_artifact_access
set_artifact_access      create_share_link        list_share_links
revoke_share_link        list_audit_events        resolve_path

​
Examples

{
  "tool": "create_artifact",
  "input": {
    "ownerUsername": "alice",
    "projectSlug": "default",
    "slug": "research-brief",
    "type": "md",
    "title": "Research brief",
    "content": "# Research brief\n\nFindings...",
    "access": { "publicView": true, "publicEdit": false }
  }
}

​
Which surface should an agent use?

UseWhen
MCPThe client keeps a long-lived authenticated connection and benefits from structured tool discovery
CLIThe agent is shell-first or running in a CI job
RESTYou’re integrating from your own backend

MCP reference

Endpoint metadata, the full tool list, and input schemas.