echolot mcp

echolot mcp works with MCP servers in two directions. check and sign-in talk to someone else's server, as the MCP Servers page does. serve and setup make your workspace an MCP server, so AI agents such as Claude Code or Cursor can list, send and test its requests; see agents.

echolot mcp checkCopy Anchor Link

echolot mcp check [--url <url>] [--header <header> ...] [--env <env> ...] [--verbose] [--timeout <seconds>] [--quality] [--strict] [--as <provider>] -- [<command> ...]

Give a Streamable HTTP endpoint with --url, or the command that starts a stdio server after --. Echolot finds out whether the server speaks the stateless protocol (2026-07-28) or an earlier one with a handshake, and lists its tools, resources and prompts:

echolot mcp check --url https://demo.echolot.dev/mcp

alpenglow-mcp 1.5.0: MCP 2025-11-25 (session, initialize)
  connected in 263 ms, round trip 54 ms
  instructions: The Alpenglow demo shop from docs.echolot.dev. Read-only: search the catalog, look up products and orders.
3 tools
  search_catalog: Searches the Alpenglow catalog by text and returns matching products with price and stock.
  get_product: Returns one product by SKU, with its price, weight, rating and stock per warehouse.
  order_status: Returns an order's status, total and shipping estimate.
1 resource
  alpenglow://catalog/categories  categories
1 prompt
  pack_for_a_trip: Suggests gear for a trip.

A stdio server:

echolot mcp check -- npx -y @modelcontextprotocol/server-everything
echolot mcp check -e API_KEY=demo -- uvx some-mcp-server --flag

How a model sees the toolsCopy Anchor Link

--quality adds what a model would get from the server: what the tool list costs in each provider's context on every turn (an estimate), the tools that cost the most, and what a model would stumble over, such as schema problems and unclear or overlapping descriptions. It is the same report as How a model sees this server in the app; see tools and quality.

echolot mcp check --url https://demo.echolot.dev/mcp --quality

How a model sees the tools (estimates)
  Anthropic      572 tokens a turn, 0.3% of a 200k context
  OpenAI         166 tokens a turn, 0.1% of a 200k context
  Google Gemini  225 tokens a turn, 0.1% of a 200k context
  largest: search_catalog 98, get_product 66, order_status 62
Nothing a model would stumble over.

--strict makes a problem (not a warning or a note) exit with 1, for CI. --as anthropic, --as openai or --as gemini prints only the tool list as that provider's API receives it.

echolot mcp sign-in and sign-outCopy Anchor Link

echolot mcp sign-in <server> [--workspace <workspace>] [--env <env>] [--force] [--print] [--verbose]
echolot mcp sign-out <server> [--workspace <workspace>]

<server> is the server's file name in the workspace's mcp-servers folder, without .toml. Sign-in opens your browser and waits for the redirect on 127.0.0.1:

echolot mcp sign-in alpenglow-mcp -w Alpenglow.echolot

• On a Mac, the sign-in goes to the Keychain, shared with the app: the app and echolot run on this Mac use it.
• Elsewhere, or with --print, Echolot prints it as an ECHOLOT_SECRET_…='…' line. Keep that value as a CI secret and set the variable where Echolot runs. It holds a refresh token: treat it like a password.
• ECHOLOT_BROWSER names another command to open the sign-in page with.

sign-out removes the sign-in from the Keychain. Without a Keychain there is nothing to forget: remove the variable instead.

echolot mcp serveCopy Anchor Link

echolot mcp serve [<workspace>] [--env <env>] [--policy <policy>] [--toolsets <toolsets>] [--http <port>] [--verbose] [--headless] [--trust-workspace-policy]

Serves a workspace to agents over MCP. Agents list, read, send and run its requests, query responses by handle, and create or change requests, through the same tools as the app. Add it to a client as a stdio server whose command is:

echolot mcp serve /path/to/Alpenglow.echolot

With the app open. When the Echolot app has the workspace open and lets agents in (Settings › Agents), the client is put through to the app. The app then asks you to approve what needs approval, and you see what the agent does. --headless serves on its own anyway.

On its own. Without the app, nobody can be asked, so what the policy would ask about is refused:

Secrets resolve from ECHOLOT_SECRET_ variables and this Mac's Keychain, and never reach the agent. Headless, the server runs only the scripts the workspace had when it started.

The workspace's own rules. An [agents] section in workspace.toml can turn agents off for the workspace, or make the policy stricter per kind of action. Rules that would loosen the policy only count with --trust-workspace-policy; without it Echolot says which ones it ignored. A new host and a protected environment are never allowed outright. The keys are in workspace files.

Toolsets. requests is always offered. --toolsets adds groups, comma-separated, or all:

The agent policy, proxy, certificates, auth settings and scripts are never offered to agents, in any toolset.

Over HTTP. --http <port> serves Streamable HTTP on 127.0.0.1 instead of stdio (0 picks a free port). Since anything on this Mac can reach a loopback port, clients must send a bearer token, which Echolot prints:

echolot mcp serve Alpenglow.echolot --http 0 --policy readonly

Echolot MCP server for Alpenglow at http://127.0.0.1:52817/mcp (policy readonly)
Clients send the header  Authorization: Bearer 6f1c…

Set ECHOLOT_MCP_TOKEN to choose the token yourself.

echolot mcp setupCopy Anchor Link

echolot mcp setup <client> [--workspace <workspace>] [--name <name>] [--version <version>]

Prints what a client needs to start echolot mcp serve for a workspace. It changes nothing; copy the output where the client reads it. The command in the output is the path of the echolot you ran.

echolot mcp setup claude-code -w Alpenglow.echolot

claude mcp add --scope user echolot-alpenglow -- /usr/local/bin/echolot mcp serve /Users/you/Alpenglow.echolot

echolot mcp setup cursor -w Alpenglow.echolot

{
  "mcpServers" : {
    "echolot-alpenglow" : {
      "args" : ["mcp", "serve", "/Users/you/Alpenglow.echolot"],
      "command" : "/usr/local/bin/echolot"
    }
  }
}

Settings › Agents in the app sets up the same clients for you; see agents.

Exit codesCopy Anchor Link