Documentation
¶
Overview ¶
Package mcp is Atlas's Model Context Protocol server: it lets an AI agent drive a running Atlas server through tools — deploy a BPMN model, manage design-time projects and artifacts, start an instance, complete human tasks, and inspect live runtime state.
Shape: an adapter over the HTTP API, on two transports ¶
The server speaks JSON-RPC 2.0 and translates each tool call into an HTTP request against a running Atlas server; it holds no engine state of its own. Two transports share one dispatch path:
- stdio (Serve) — newline-delimited JSON, one message per line. This is the MCP stdio transport a local client (Claude Desktop, Claude Code) spawns.
- Streamable HTTP (ServeHTTP) — the remote transport. Mount it at a path such as /mcp and a remote client can reach the same tools. It performs no authentication; front it with a reverse proxy before exposing it publicly.
This is deliberate. The engine is a single-writer partition (invariant I3): exactly one goroutine may touch a partition's processor and state, a discipline the api package already enforces behind its HTTP surface. By proxying to that surface rather than embedding the engine, the MCP server can never violate an engine invariant — it only ever makes HTTP calls. It is a pure adapter, and an AI agent sees the same deployments and instances a human sees in the web UI.
Project deletion ¶
A design-time project is a grouping folder, not an execution aggregate (ADR-0034). atlas_delete_project therefore calls the public project DELETE endpoint and removes only that folder. Drafts and decision references tagged with its id remain available as ungrouped artifacts; deployed definitions and process instances are unaffected. The API operation is idempotent and enforces the project owner role when authentication is enabled.
No new dependencies ¶
The protocol is implemented by hand (see server.go), matching the repository's preference for small, self-contained code over pulled-in SDKs. The only surface area is the four MCP methods a tools-only server needs: initialize, tools/list, tools/call, and ping.
Running it ¶
Remote (Streamable HTTP) — atlas serve mounts the transport at /mcp:
atlas serve --addr :8080 # engine + HTTP API + UI + /mcp
Local (stdio) — a per-agent, short-lived adapter an MCP client spawns:
atlas mcp --server http://localhost:8080
For stdio, diagnostics go to stderr; stdout carries protocol traffic only.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a thin HTTP client for the Atlas server API (see the api package). The MCP server owns no engine state of its own; every tool call is translated into an HTTP request against a running Atlas server, which remains the single writer of its partition (invariant I3). That keeps the MCP surface a pure adapter — it can never violate an engine invariant because it never touches the engine directly.
func NewClient ¶
func NewClient(baseURL string, opts ...ClientOption) *Client
NewClient builds a Client for the Atlas server at baseURL (e.g. "http://localhost:8080"). A trailing slash is tolerated.
type ClientOption ¶
type ClientOption func(*Client)
ClientOption configures a Client at construction.
func WithBearer ¶
func WithBearer(token string) ClientOption
WithBearer attaches an Authorization: Bearer <token> header to every request. The single-binary server uses it so the in-process adapter can authenticate its loopback calls when the API requires login (ADR-0049). An empty token is a no-op, so callers can pass it unconditionally.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a Model Context Protocol server that exposes the Atlas API as MCP tools over a stdio JSON-RPC 2.0 transport. It is deliberately dependency-free and hand-written, in keeping with the rest of the repository.
func NewServer ¶
NewServer builds an MCP server that proxies tool calls to the Atlas server reachable through client.
func (*Server) Serve ¶
Serve runs the JSON-RPC loop, reading newline-delimited messages from in and writing responses to out, until in reaches EOF. It returns the first read error, or nil on a clean EOF. Diagnostics must never be written to out (that is the protocol channel); callers should log to stderr.
func (*Server) ServeHTTP ¶
func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP makes Server an http.Handler implementing the MCP "Streamable HTTP" transport, so the same tool surface reachable over stdio (Serve) can be mounted at a path such as /mcp and reached by a remote MCP client — for example a claude.ai custom connector.
Message dispatch is shared with the stdio loop via handle; this method is transport only. The handler is stateless: it assigns no Mcp-Session-Id and requires none, which is sufficient for a tools-only server.
Security: this endpoint performs NO authentication. Anything that can reach it can deploy and run processes. Do not expose it publicly without authentication in front of it (e.g. at a reverse proxy).
type Tool ¶
type Tool struct {
Name string
Description string
InputSchema map[string]any
Handler func(c *Client, args map[string]any) (string, error)
}
Tool is one MCP tool: its advertised name, human/model-facing description, JSON Schema for arguments, and the handler that fulfils a call by talking to the Atlas server.
Source Files