MCP server

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:

Discover metadata

The client fetches the protected resource metadata.

The client dynamically registers, if it supports dynamic registration.

Consent

The user completes browser consent and Google sign-in.

Exchange a token

The client exchanges the authorization code for a bearer token.

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 }
  }
}

{
  "tool": "update_artifact",
  "input": {
    "artifactId": "ARTIFACT_ID",
    "content": "# Research brief\n\nUpdated findings...",
    "changelog": "Refresh findings"
  }
}

{
  "tool": "resolve_path",
  "input": {
    "ownerUsername": "alice",
    "projectSlug": "default",
    "slug": "research-brief"
  }
}

Which surface should an agent use?

Use	When
MCP	The client keeps a long-lived authenticated connection and benefits from structured tool discovery
CLI	The agent is shell-first or running in a CI job
REST	You’re integrating from your own backend

MCP reference

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

Get started

Core concepts

Task guides

Ways to connect

Endpoint

Discovery metadata

How a client connects

Tools

Examples

Which surface should an agent use?

MCP reference

​Endpoint

​Discovery metadata

​How a client connects

​Tools

​Examples

​Which surface should an agent use?

MCP reference

Endpoint

Discovery metadata

How a client connects

Tools

Examples

Which surface should an agent use?