From 094d14711ab3b7e00d8e15c1b2b74042be23ba93 Mon Sep 17 00:00:00 2001 From: joaocosta9 Date: Sat, 25 Jul 2026 17:58:30 +0100 Subject: [PATCH] docs: show how to add the MCP server to Claude The README gave a JSON blob and left readers to work out where it goes. Lead with the `claude mcp add` one-liner instead, keep the JSON for Desktop and other clients, and say the two things people trip on: scope, and that a running session will not pick the server up until it restarts. Drops the "7-day" claim on the token, which the docs should not promise while the api does not enforce it. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 42 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 37 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 23a2bbb..2843cf5 100644 --- a/README.md +++ b/README.md @@ -87,26 +87,58 @@ The server speaks [MCP](https://modelcontextprotocol.io) over streamable HTTP at `/mcp` on the api host, so an agent can provision sandboxes, drive them and hand back explorer links a human can open. -Authentication is the same 7-day JWT as the REST api: +### 1. Get a token + +Authentication is the same JWT as the REST api. The code arrives by email: + +```bash +curl -X POST https://api.stacks.ethui.dev/auth/send-code \ + -H 'content-type: application/json' \ + -d '{"email":"you@example.com"}' + +curl -X POST https://api.stacks.ethui.dev/auth/verify-code \ + -H 'content-type: application/json' \ + -d '{"email":"you@example.com","code":"123456"}' +# -> {"token":"eyJ..."} +``` + +### 2. Add the server + +Claude Code: ```bash -curl -X POST https://api.stacks.ethui.dev/auth/send-code -d '{"email":"you@example.com"}' -curl -X POST https://api.stacks.ethui.dev/auth/verify-code -d '{"email":"you@example.com","code":"123456"}' +claude mcp add --transport http --scope user ethui-stacks \ + https://api.stacks.ethui.dev/mcp \ + --header "Authorization: Bearer eyJ..." ``` +`--scope user` makes it available in every project; drop it to add the server to +the current one only. Check it with `claude mcp list`, then restart Claude Code — +MCP servers are loaded when a session starts. + +Claude Desktop, and other clients that take JSON: + ```json { "mcpServers": { "ethui-stacks": { "type": "http", "url": "https://api.stacks.ethui.dev/mcp", - "headers": { "Authorization": "Bearer " } + "headers": { "Authorization": "Bearer eyJ..." } } } } ``` -Tools: +The token sits in that config in plaintext. Claude Code expands environment +variables, so `"Bearer ${ETHUI_STACKS_TOKEN}"` works if you would rather keep it +out of the file. + +Point `url` at your own instance to use a self-hosted Stacks. Running without +`ETHUI_STACKS_SAAS` disables authentication entirely, so the header can be +dropped locally. + +### Tools - lifecycle: `create_stack` `list_stacks` `delete_stack` - reads: `get_block` `get_transaction` `get_address` `get_logs`