@augstash/mcp
v0.1.3
Published
Model Context Protocol server for Augstash - the whole API as tools, in toolsets you choose, for Claude, ChatGPT, Cursor and any MCP client
Readme
@augstash/mcp
Use your Augstash workspace from an AI assistant — Claude, ChatGPT, Cursor and any other MCP client. It covers the same API as the Augstash SDKs: the tools are generated from the same OpenAPI spec, so they never drift from the API.
You decide how much the assistant may see and do:
| Dial | Choices | Default |
|---|---|---|
| Areas (toolsets) | inbox, contacts, whatsapp, sms, emails, wallet, … 36 in all (--list-toolsets) | the everyday core: inbox, contacts, whatsapp, sms, emails, wallet |
| Access | read · write (changes + single sends) · full (deletes, bulk sends, billing) | read |
Nothing in /admin, /internal, sign-in or API-key management is ever exposed.
Connect — easiest: sign in with Augstash
In Claude (claude.ai → Settings → Connectors) or ChatGPT (Settings → Connectors → Add), add a custom connector with the URL
https://mcp.augstash.com/mcpYou are sent to a Connect Augstash page: pick what the assistant may do, sign in with your Augstash email and password (or paste an API key if you use SSO), and approve. That creates a dedicated key just for this connection, limited to exactly what you ticked. Revoke it any time under Settings → API keys and the assistant loses access immediately.
Connect — with an API key
- Create a key in the console (Settings → API keys) with only the scopes you want.
- Claude Code:
claude mcp add --transport http augstash "https://mcp.augstash.com/mcp?toolsets=inbox,contacts&access=read" \
--header "Authorization: Bearer ask_live_xxx.yyy"Cursor / Claude Desktop / Windsurf / VS Code (mcp.json):
{
"mcpServers": {
"augstash": {
"url": "https://mcp.augstash.com/mcp?toolsets=core&access=read",
"headers": { "Authorization": "Bearer ask_live_xxx.yyy" }
}
}
}Or run it locally over stdio (nothing leaves your machine except calls to the Augstash API):
{
"mcpServers": {
"augstash": {
"command": "npx",
"args": ["-y", "@augstash/mcp"],
"env": { "AUGSTASH_API_KEY": "ask_live_xxx.yyy", "AUGSTASH_TOOLSETS": "core", "AUGSTASH_ACCESS": "read" }
}
}
}toolsets is core, all, or a list (inbox,wallet). Too many tools makes assistants worse at picking one,
so enable only the areas you need.
Safety
- Your key, your limits. The server holds no credentials of its own. Augstash decides your workspace, scopes, rate limit and wallet on every call; the server never takes a workspace id from a tool call.
- Two locks. Hiding a tool is a convenience; the key's scopes are the real limit. A hidden tool can't be called by guessing its name, and a connection made through the sign-in page cannot be widened by editing the URL.
- Sends are labelled. Tools that change data or message people say so, are marked non-read-only, and
anything that deletes, fans out to many people or touches billing needs
fullaccess. Keep your client's "approve each tool call" setting on for those. - Every change carries an idempotency key (pass
idempotencyKeyto make a retry a replay). - Revoking the key in the console cuts the assistant off at once, on every platform.
Run your own copy
AUGSTASH_BASE_URL=https://api.augstash.com \
AUGSTASH_MCP_PUBLIC_URL=https://mcp.example.com \
AUGSTASH_MCP_SECRETS="<32+ random chars>[,<older secret>]" \
npx @augstash/mcp --http --port 8090Stateless — no database, no sessions; run as many replicas as you like. Without AUGSTASH_MCP_SECRETS
the OAuth sign-in is off and only API keys work. Rotate by putting the new secret first and keeping the old
one until the 90-day refresh tokens it sealed have expired. Container: docker build -f sdk/mcp/Dockerfile -t augstash-mcp sdk.
Develop
npm install && npm test # regenerates the catalogue from ../spec, typechecks, runs the suite
npm run generate # just rebuild catalog.json after recapturing sdk/spec