> ## Documentation Index
> Fetch the complete documentation index at: https://artifacts.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect MCP clients to Artifacts and call artifact tools directly.

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.

<Info>
  This page covers connecting and using MCP. For every tool and its input schema, see the [MCP reference](/reference/mcp).
</Info>

## Endpoint

When running locally:

```text theme={"theme":"github-dark"}
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

```text theme={"theme":"github-dark"}
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:

<Steps>
  <Step title="Discover metadata">
    The client fetches the protected resource metadata.
  </Step>

  <Step title="Register">
    The client dynamically registers, if it supports dynamic registration.
  </Step>

  <Step title="Consent">
    The user completes browser consent and Google sign-in.
  </Step>

  <Step title="Exchange a token">
    The client exchanges the authorization code for a bearer token.
  </Step>

  <Step title="Call tools">
    The client calls `/mcp` with `authorization: Bearer ...`.
  </Step>
</Steps>

## Tools

Every tool takes structured JSON and returns domain objects, validated with the same Zod schemas as the REST and CLI paths.

```text theme={"theme":"github-dark"}
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

<CodeGroup>
  ```json Create theme={"theme":"github-dark"}
  {
    "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 }
    }
  }
  ```

  ```json Update theme={"theme":"github-dark"}
  {
    "tool": "update_artifact",
    "input": {
      "artifactId": "ARTIFACT_ID",
      "content": "# Research brief\n\nUpdated findings...",
      "changelog": "Refresh findings"
    }
  }
  ```

  ```json Resolve path theme={"theme":"github-dark"}
  {
    "tool": "resolve_path",
    "input": {
      "ownerUsername": "alice",
      "projectSlug": "default",
      "slug": "research-brief"
    }
  }
  ```
</CodeGroup>

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

<Card title="MCP reference" icon="plug" href="/reference/mcp" horizontal>
  Endpoint metadata, the full tool list, and input schemas.
</Card>