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

# Atlas MCP

> Connect Atlas capabilities to host agents through local or remote MCP.

Atlas MCP lets a host agent call Atlas during its own workflow. The MCP server applies the connected user's permissions and returns MCP text, structured content, and resources.

## Local and Remote MCP

| Mode | Runtime | Auth | Local files | Use case |
| - | - | - | - | - |
| Local MCP | Process on the user's machine. | Signed-in local Atlas profile. | Host-approved `file://` URIs can be passed to Atlas. | Local agent workflows with local evidence. |
| Remote MCP | Atlas-hosted HTTP server. | Connected user's bearer token. | Atlas file URIs, inline text, or base64 blobs can be passed to Atlas. | Hosted agents and shared agent environments. |

Both modes expose the same Atlas tools and structured result fields.

## Start Local MCP

```bash theme={null}
atlas setup-url https://atlas.example.com
atlas login
atlas mcp serve
```

`atlas login` uses device authorization and stores the user token locally. The MCP server reads that profile and sends Atlas calls under the signed-in user's permissions.

Local MCP runs over stdio by default. The host sends JSON-RPC messages to the server on `stdin`. The server writes JSON-RPC messages to `stdout` and writes logs to `stderr`.

When the host supports MCP roots, the local server requests `roots/list` and rejects `file://` inputs outside those roots.

## Connect to Remote MCP

```http theme={null}
POST /mcp HTTP/1.1
Host: atlas.example.com
Authorization: Bearer <atlas-user-access-token>
Accept: application/json, text/event-stream
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "clientInfo": {
      "name": "host-agent",
      "version": "1.0.0"
    },
    "capabilities": {}
  }
}
```

If the host starts without a token, Atlas returns an OAuth challenge. The host follows the advertised authorization server metadata and reconnects with the user token.

Remote MCP uses Streamable HTTP. Each client message is an HTTP `POST` to `/mcp`. Long requests can return Server-Sent Events, including MCP progress notifications before the final JSON-RPC response. The user bearer token is required on every HTTP request.

## Discover Tools

The host discovers Atlas tools through MCP `tools/list`. Atlas publishes a small registry of product-level tools.

| Tool | Use when | Returns |
| - | - | - |
| `atlas.request` | The host starts a new Atlas interaction. | Answer, session metadata, objects, files, artifacts, actions, and resource links. |
| `atlas.reply` | The host continues a prior Atlas session. | Follow-up answer and updated structured results. |
| `atlas.approve_action` | The user has reviewed a proposed write action. | Updated action status and any resulting Atlas objects or links. |

Atlas tools start work, continue work, or apply an action decision. Returned objects, files, and artifacts are MCP resources fetched by URI.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "atlas.request",
        "description": "Start an Atlas request with an instruction and caller-provided context.",
        "inputSchema": {
          "type": "object",
          "required": ["input"],
          "properties": {
            "input": {
              "type": "string"
            },
            "intent": {
              "type": "string",
              "enum": ["answer", "search", "artifact", "propose_write"]
            },
            "context": {
              "type": "object",
              "properties": {
                "files": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "uri": {
                        "type": "string"
                      },
                      "text": {
                        "type": "string"
                      },
                      "blob": {
                        "type": "string"
                      },
                      "mimeType": {
                        "type": "string"
                      }
                    },
                    "anyOf": [
                      { "required": ["uri"] },
                      { "required": ["text"] },
                      { "required": ["blob", "name", "mimeType"] }
                    ]
                  }
                },
                "inlineText": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": ["text"],
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "text": {
                        "type": "string"
                      },
                      "mimeType": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      {
        "name": "atlas.reply",
        "description": "Continue an Atlas session returned by a prior Atlas request.",
        "inputSchema": {
          "type": "object",
          "required": ["session_id", "input"],
          "properties": {
            "session_id": {
              "type": "string"
            },
            "input": {
              "type": "string"
            },
            "context": {
              "type": "object",
              "properties": {
                "files": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "uri": {
                        "type": "string"
                      },
                      "text": {
                        "type": "string"
                      },
                      "blob": {
                        "type": "string"
                      },
                      "mimeType": {
                        "type": "string"
                      }
                    },
                    "anyOf": [
                      { "required": ["uri"] },
                      { "required": ["text"] },
                      { "required": ["blob", "name", "mimeType"] }
                    ]
                  }
                },
                "inlineText": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": ["text"],
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "text": {
                        "type": "string"
                      },
                      "mimeType": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      {
        "name": "atlas.approve_action",
        "description": "Approve or reject a proposed Atlas action returned by Atlas.",
        "inputSchema": {
          "type": "object",
          "required": ["action_id", "decision"],
          "properties": {
            "action_id": {
              "type": "string"
            },
            "decision": {
              "type": "string",
              "enum": ["approve", "reject"]
            }
          }
        }
      }
    ]
  }
}
```

## Start a Request

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "atlas.request",
    "arguments": {
      "input": "Summarize this IMU bring-up log and return related Atlas results.",
      "intent": "answer",
      "context": {
        "files": [
          {
            "name": "imu-bringup.txt",
            "uri": "file:///Users/alex/logs/imu-bringup.txt"
          }
        ]
      }
    }
  }
}
```

`intent` controls the request shape. Supported values are `answer`, `search`, `artifact`, and `propose_write`.

## Pass Files

MCP file inputs are request context. Atlas accepts these forms:

| Form | Local MCP | Remote MCP | Use case |
| - | - | - | - |
| `file://` URI | Supported when the path is inside host-approved roots. | Unsupported. | Local files selected by the host agent. |
| `atlas://file/{id}` URI | Supported. | Supported. | Files already uploaded to Atlas. |
| `text` | Supported. | Supported. | Small text files, logs, snippets, and generated text. |
| `blob` | Supported. | Supported. | Small binary files encoded as base64. |

Use `file://` only with local MCP. For remote MCP, upload the file to Atlas first or pass small content inline. Atlas MCP converts inline `text` and `blob` inputs to Atlas file handles before it calls the Agentic API.

```json theme={null}
{
  "name": "atlas.request",
  "arguments": {
    "input": "Summarize this test log.",
    "context": {
      "files": [
        {
          "name": "imu-bringup.txt",
          "mimeType": "text/plain",
          "text": "2026-06-24T18:41:03Z spi read timeout..."
        }
      ]
    }
  }
}
```

## Continue a Session

Use `atlas.reply` with the `session_id` returned by a prior Atlas response.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "atlas.reply",
    "arguments": {
      "session_id": "session_123",
      "input": "Generate the investigation summary as an artifact."
    }
  }
}
```

## Track Progress

Hosts request progress by adding an MCP `progressToken` to the tool call metadata.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "_meta": {
      "progressToken": "request_abc"
    },
    "name": "atlas.request",
    "arguments": {
      "input": "Generate an investigation artifact from this capture.",
      "intent": "artifact",
      "context": {
        "files": [
          {
            "uri": "atlas://file/file_123"
          }
        ]
      }
    }
  }
}
```

Atlas sends MCP `notifications/progress` while the request runs. Hosts cancel active requests with `notifications/cancelled`.

## Read Results

Atlas MCP returns an answer in `content`, compact records in `structuredContent`, and resource links for full objects, files, and artifacts.

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "Atlas found one related issue and generated an investigation artifact."
    },
    {
      "type": "resource_link",
      "uri": "atlas://artifact/artifact_456",
      "name": "investigation-summary.pdf",
      "mimeType": "application/pdf"
    }
  ],
  "structuredContent": {
    "metadata": {
      "session_id": "session_123",
      "request_id": "request_456"
    },
    "objects": [
      {
        "type": "issue",
        "id": "issue_123",
        "title": "Intermittent IMU SPI read failure",
        "status": "open",
        "summary": "Prior rev C reports show the same SPI read pattern.",
        "link": "atlas://object/issue/issue_123"
      }
    ],
    "artifacts": [
      {
        "id": "artifact_456",
        "artifact_type": "investigation_summary",
        "name": "investigation-summary.pdf",
        "status": "completed",
        "link": "atlas://artifact/artifact_456"
      }
    ]
  }
}
```

## Fetch Returned Resources

Returned files, artifacts, and full object records are URI-addressed. The host reads a linked object, file, or artifact through MCP `resources/read`.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "resources/read",
  "params": {
    "uri": "atlas://artifact/artifact_456"
  }
}
```

```json theme={null}
{
  "contents": [
    {
      "uri": "atlas://artifact/artifact_456",
      "mimeType": "application/pdf",
      "blob": "<base64-encoded-content>"
    }
  ]
}
```

Text resources return `text`. Binary resources return `blob`. Resource reads use the connected user's Atlas permissions.

## Approve Actions

Write operations are returned as proposed actions. The host agent shows the action to the user and calls Atlas after approval.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "atlas.approve_action",
    "arguments": {
      "action_id": "action_789",
      "decision": "approve"
    }
  }
}
```

Atlas applies the connected user's permissions again when the action is approved.

## Tool Argument Types

```ts theme={null}
type AtlasMcpFileInput =
  | { uri: string; name?: string; mimeType?: string }
  | { text: string; name?: string; mimeType?: string }
  | { blob: string; name: string; mimeType: string };

type AtlasMcpRequestArguments = {
  input: string;
  intent?: "answer" | "search" | "artifact" | "propose_write";
  context?: {
    files?: AtlasMcpFileInput[];
    inlineText?: Array<{
      name?: string;
      text: string;
      mimeType?: string;
    }>;
  };
};

type AtlasMcpReplyArguments = {
  session_id: string;
  input: string;
  context?: AtlasMcpRequestArguments["context"];
};

type AtlasMcpApproveActionArguments = {
  action_id: string;
  decision: "approve" | "reject";
};
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.