# Connecting an AI assistant to your workspace over MCP

Give an external AI assistant read access to your workspace records, maps, and schema through the Model Context Protocol endpoint.

Your Saw Your Sign workspace has a built-in [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. You can connect Claude Desktop, an IDE agent, or any other MCP-compatible client and let it read your workspace data: records, saved maps, and your schema (record types and custom fields).

This feature is in beta. In the current version (v1), external connections over a token are **read-only**. The AI can look at your data and plan changes, but all write operations (creating maps, importing records, etc.) require an interactive session in the dashboard. External write access is planned for a future release.

## What you need

- A Saw Your Sign workspace on a plan that includes API access
- An API token with at least one read scope (`records:read`, `maps:read`, or both)
- An MCP client such as Claude Desktop

## Step 1: Mint an API token

Go to your workspace settings and open **API tokens**. Create a new token and select the scopes you want the AI assistant to have:

- **`records:read`** lets the assistant read your records and your workspace schema (record types, custom fields, and map configuration options).
- **`maps:read`** lets the assistant read your saved maps. It also satisfies the schema scope on its own.

Copy the token string when it is shown. It looks like `sys_live_t_<id>.<secret>` and is displayed only once.

## Step 2: Add the server to your MCP client

For Claude Desktop, open your `claude_desktop_config.json` file and add an entry under `mcpServers`:

```json
{
  "mcpServers": {
    "saw-your-sign": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://sawyoursign.com/api/mcp",
        "--header",
        "Authorization: Bearer sys_live_t_<id>.<secret>"
      ]
    }
  }
}
```

Replace `sys_live_t_<id>.<secret>` with the token you copied. If you are on a self-hosted instance, replace `sawyoursign.com` with your host.

The `mcp-remote` package bridges the remote HTTP server to the local stdio transport that Claude Desktop expects, passing your token as an `Authorization` header. `npx` downloads it automatically on first use. Any MCP client that can send an `Authorization` header to an HTTP endpoint can connect the same way.

## What the AI assistant can read

Once connected, the assistant has access to three workspace resources:

**`workspace://schema`** gives the assistant your record types, all custom field definitions, and the available map themes, visibility modes, and privacy modes. Requires `maps:read` or `records:read` (either one is enough; an unrelated scope such as `galleries:read` is not).

**`workspace://maps`** lists your saved maps. Requires `maps:read`.

**`workspace://records`** returns a bounded set of record summaries (up to 100 at a time). You can narrow it by record type: the URI `workspace://records?recordType=job&limit=25` returns up to 25 records of type `job`. Requires `records:read`.

## What the AI assistant can do (and cannot do)

With a read-only token the assistant can:

- Read your records, maps, and schema
- Use the `preview_action` tool to validate a proposed change (such as creating a map or importing records) without actually applying it

The assistant cannot, over a token:

- Create or update record types, fields, or maps
- Import records
- Archive fields
- Roll back previous assistant actions

These operations are only available through the dashboard's built-in AI assistant, which authenticates with your browser session. If you ask an external assistant to make changes, it will tell you the action is not available for token access.

## Security notes

Your token authenticates as your workspace but with reduced privileges. It does not carry your full role: the server treats token requests as guest-level regardless of who created the token. Your tenant is determined by the token itself; the client cannot claim a different workspace.

If you share a token or it is exposed, revoke it from **Settings > API tokens** immediately. Revoked tokens stop working at the next request.