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

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

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.

{
  "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

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "resources/read",
  "params": {
    "uri": "atlas://artifact/artifact_456"
  }
}

{
  "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.

{
  "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

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