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

# MCP Server

> Access Atomscale from Claude, IDEs, and other AI agents over the Model Context Protocol

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard for connecting AI applications to external systems. The Atomscale MCP server lets AI tools search, analyze, and manage your metrology data — RHEED, SEM, XPS, ellipsometry, Raman, photoluminescence, and more — directly, without leaving your assistant.

Every request is scoped to your Atomscale account: tools act as **you**, within **your organization**, and respect the same permissions as the web app.

## Endpoint

```
https://api.atomscale.ai/mcp/
```

The server speaks streamable-HTTP. The trailing slash is required.

## Setup

On first connection your client opens a browser to sign in with your Atomscale account, then caches a token for subsequent requests. Headless clients can authenticate with an API key instead (see [Authentication](#authentication)).

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http atomscale https://api.atomscale.ai/mcp/
    ```

    Then run `/mcp` inside Claude Code to complete sign-in and list the tools.
  </Tab>

  <Tab title="Claude Desktop / claude.ai">
    Go to **Settings → Connectors → Add custom connector**, then enter:

    ```
    https://api.atomscale.ai/mcp/
    ```

    Approve the access request when prompted.
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "atomscale": {
          "url": "https://api.atomscale.ai/mcp/"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other">
    Most MCP clients accept a remote server via `mcpServers` config:

    ```json theme={null}
    {
      "mcpServers": {
        "atomscale": {
          "url": "https://api.atomscale.ai/mcp/"
        }
      }
    }
    ```

    Clients that don't support the interactive OAuth flow can send an API key as a Bearer token — see [Authentication](#authentication).
  </Tab>
</Tabs>

## Authentication

<Tabs>
  <Tab title="OAuth (default)">
    Interactive clients sign in through your browser on first connect. There's nothing to configure — approve the access request and the client caches its token.
  </Tab>

  <Tab title="API key (headless)">
    For CI, scripts, or clients without a browser, send your API key as a Bearer token:

    ```json theme={null}
    {
      "mcpServers": {
        "atomscale": {
          "url": "https://api.atomscale.ai/mcp/",
          "headers": { "Authorization": "Bearer YOUR_API_KEY" }
        }
      }
    }
    ```

    Generate a key from the [Atomscale Dashboard](https://app.atomscale.ai) under **User → Manage Account → Access**.

    <Warning>Never commit your API key to version control. Use environment variables or a secrets manager.</Warning>
  </Tab>
</Tabs>

## Tools

Your assistant chooses which tools to call. Write tools (marked below) prompt for confirmation in most clients before making changes.

| Tool               | Access | Description                                              |
| ------------------ | ------ | -------------------------------------------------------- |
| `search_data`      | Read   | Search the data catalogue                                |
| `fetch_data`       | Read   | Get one data item's metadata by ID                       |
| `fetch_results`    | Read   | Processed analysis results or AI summary for a data item |
| `fetch_embeddings` | Read   | Similarity embeddings for a data item                    |
| `search_sample`    | Read   | Search physical samples                                  |
| `fetch_sample`     | Read   | Get one physical sample by ID                            |
| `list_notebooks`   | Read   | List your organization's analysis notebooks              |
| `annotate_data`    | Write  | Apply tags and/or attach a note to a data item           |
| `add_notebooks`    | Write  | Create an analysis notebook                              |
| `edit_notebooks`   | Write  | Commit a new version of a notebook                       |
| `upload_data`      | Write  | Get presigned URLs to upload a new file                  |
| `start_stream`     | Write  | Start a timeseries stream                                |
| `stop_stream`      | Write  | Finalize a stream                                        |

<Note>A `ping` tool is also available for liveness checks and requires no authentication.</Note>