{
  "markdown": "# @savantoai/mcp-server\n\nA local [Model Context Protocol](https://modelcontextprotocol.io) server that exposes your Savanto AI workspace to Claude, ChatGPT, Cursor, and any other MCP-compatible client — so you can **configure, populate, and operate your store's AI assistant by talking to your own AI**, instead of clicking through a dashboard.\n\n## What it does\n\nOnce configured, your agent gains a curated set of tools that mirror the Savanto REST API, spanning the full **configure → observe → refine** loop:\n\n| Category | Representative tools | Scope |\n| --- | --- | --- |\n| Workspaces | `list_workspaces`, `create_workspace`, `update_workspace`, `delete_workspace` | `tenant:admin` |\n| Configuration | `get_workspace_settings`, `update_workspace_settings`, custom-domain CRUD, `discover_tools`, `generate_domain_config`, `validate_custom_domain`, `test_domain_connection`, `generate_color_scheme`, chat/search widget config | `config:admin` |\n| Content | `upsert_product`/`upsert_post` (+ `bulk_*`, `list_*`, `get_*`, `patch_*`, `delete_*`) | `admin:products`, `admin:posts` |\n| Taxonomies | `upsert_taxonomy`, `bulk_upsert_taxonomies`, `list/get/delete_taxonomy` | `admin:taxonomies` |\n| Prompts | `upsert_prompt`, `list_prompts`, `search_prompts`, `delete_prompt` (+ bulk) | `admin:prompts`, `prompts:read` |\n| Webhooks | `create_webhook`, `list/get/update/delete_webhook`, `test_webhook`, `get_webhook_stats` | `admin:webhooks` |\n| Crawl | `start_crawl`, `get_crawl_status`/`history`/`config`, `update_crawl_config` | `admin:posts` |\n| Search | `search_products`, `search_posts` | `search:products`, `search:posts` |\n| Analytics | `get_search_analytics`, `get_chat_analytics`, `get_feedback_analytics`, `search_search_logs`, `list_feedback` | `tenant:admin`, `feedback:admin` |\n| Threads | `search_threads`, `get_thread`, `get_thread_messages`, `get_thread_analytics`, `delete_thread`, `bulk_delete_threads` | `threads:admin` |\n| Chat | `chat` | `chat` |\n| Diagnostics | `whoami`, `get_tenant_usage` | (none) / `tenant:admin` |\n\nTwo things keep the surface safe and legible to clients:\n\n- **Scope-gated at startup** — the server probes `/tenant/whoami` and only registers tools your key can actually use. An agent is never shown a tool it would get a 403 for, and a publishable widget key sees almost nothing.\n- **Annotated** — every tool carries MCP hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so clients can auto-approve safe reads and flag destructive writes; deletes additionally require an explicit `confirm: true`.\n\nThe server also exposes **Skills** (MCP prompts) — step-by-step playbooks for common multi-tool workflows:\n\n- `onboard-store-end-to-end` – create a workspace, ingest content, configure behaviour + branding, smoke-test\n- `onboard-wordpress` / `onboard-shopify` – platform-specific onboarding walkthroughs\n- `configure-chat` – tune persona, special instructions, and handoff rules\n- `configure-custom-domain` – wire a custom capability (order tracking, account lookup) to MCP servers / REST APIs\n- `audit-and-improve` – the observe→refine loop: find failing chats / zero-result searches / negative feedback and fix them\n- `debug-empty-search` – diagnose why a product search returns no hits\n- `migrate-from-competitor` – bulk-import from another chat vendor's export\n\n## Requirements\n\n- Node.js 20 or later\n- A **secret** Savanto API key (starts with `if_sk_…`). Create one in the [API Keys page](https://savanto.ai/dashboard/api-keys) of your dashboard.\n  > Publishable keys (`if_pk_…`) are client-side and cannot provision workspaces — the server will refuse to start with one.\n\n## Quick start\n\nNo global install needed — run it with `npx`:\n\n```bash\nexport SAVANTO_API_KEY=if_sk_your_key_here\nnpx -y @savantoai/mcp-server\n```\n\nPoint to a non-production cloud (staging, local dev):\n\n```bash\nexport SAVANTO_API_URL=http://localhost:3001\n```\n\n## Remote server (preview)\n\nIn addition to the local stdio server above, the same tool surface can run as a\n**hosted HTTP server** so clients connect to a URL instead of spawning `npx` —\nno local Node, no per-machine config. This is the path toward one-click\n\"Connect to Claude/ChatGPT\" (OAuth) onboarding; today it accepts your secret key\nas a Bearer token.\n\n```bash\n# Each client authenticates per-request — there is NO server-wide key.\nSAVANTO_API_URL=https://api.savanto.ai PORT=8080 npx -y -p @savantoai/mcp-server savanto-mcp-http\n```\n\nThe server mounts the MCP endpoint at `/mcp` and a liveness probe at `/healthz`.\nClients send their key as `Authorization: Bearer if_sk_…`; the tool surface is\nscope-gated to that key's tenant, exactly as in the stdio server. Point an MCP\nclient that supports remote (Streamable HTTP) servers at\n`https://your-host/mcp` with that bearer token.\n\n> Auth is currently the raw secret key. A future release replaces it with\n> OAuth-issued, tenant-scoped tokens so customers can connect with zero key\n> handling — the transport and tool layer are unchanged by that swap.\n\n## Client configuration\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"savanto\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@savantoai/mcp-server\"],\n      \"env\": {\n        \"SAVANTO_API_KEY\": \"if_sk_your_key_here\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. You should see a hammer/tool icon in the message bar; the Savanto tools are listed there.\n\n### Cursor\n\nIn Cursor settings → **Features → Model Context Protocol** → **Add new MCP server**:\n\n```json\n{\n  \"savanto\": {\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"@savantoai/mcp-server\"],\n    \"env\": { \"SAVANTO_API_KEY\": \"if_sk_your_key_here\" }\n  }\n}\n```\n\n### Cline / Roo / other VS Code agents\n\nAdd to the extension's MCP config (usually a JSON file under `~/.cline` or similar):\n\n```json\n{\n  \"mcpServers\": {\n    \"savanto\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@savantoai/mcp-server\"],\n      \"env\": { \"SAVANTO_API_KEY\": \"if_sk_your_key_here\" }\n    }\n  }\n}\n```\n\n### OpenAI Agents / Responses API\n\n```python\nfrom openai import OpenAI\nfrom mcp import StdioServerParameters\n\nserver = StdioServerParameters(\n    command=\"npx\",\n    args=[\"-y\", \"@savantoai/mcp-server\"],\n    env={\"SAVANTO_API_KEY\": \"if_sk_your_key_here\"},\n)\n```\n\n### Local MCP Inspector (for debugging)\n\n```bash\nnpx @modelcontextprotocol/inspector npx @savantoai/mcp-server\n```\n\nThe Inspector gives you a web UI to list tools, call them directly, and watch request/response payloads — great for confirming your key is wired correctly before handing the server to an agent.\n\n## Example prompts\n\nOnce the server is registered in your MCP client, try:\n\n> \"Set up a new Savanto workspace for `acme-store`, crawl `https://acme.test`, give it an outdoor-adventure tone, and brand the widget around `#0a7d2c`.\" *(end-to-end onboarding)*\n\n> \"Look at `acme-store`'s last 30 days — what are visitors searching for that returns nothing, and which conversations went unresolved? Then add content to fix the top few.\" *(the observe→refine loop)*\n\n> \"Add an order-tracking capability to `acme-store` backed by our MCP server at `https://mcp.acme.test/orders`, validate it, and test it before enabling.\" *(custom domain)*\n\n> \"Why did this conversation get a thumbs-down?\" — pull `list_feedback`, read the thread, and propose a fix.\n\nThe agent picks the right tools automatically (and clients can auto-approve the read-only ones). You can also invoke a Skill explicitly — e.g. in Claude Desktop, `/onboard-store-end-to-end` or `/audit-and-improve` kicks off that full playbook.\n\n## Environment variables\n\n| Variable          | Default                         | Purpose                                          |\n| ----------------- | ------------------------------- | ------------------------------------------------ |\n| `SAVANTO_API_KEY` | _(required)_                    | Your secret API key (`if_sk_…`).                 |\n| `SAVANTO_API_URL` | `https://api.savanto.ai`        | Override for staging / local dev.                |\n\n## Security\n\n- Always use **separate API keys per agent / machine** — so you can revoke one without affecting the others. The [API Keys page](https://savanto.ai/dashboard/api-keys) tracks the last-used timestamp of each key.\n- Keys are passed via environment variables, never logged. The server prints a one-line identity banner on startup (to stderr) showing the tenant id and scope list — no secrets.\n- The server runs over stdio and never opens a network port. It only speaks to the Savanto API host you point it at.\n- `delete_workspace` requires an explicit `confirm: true` parameter in the tool call — a safety gate against hallucinated destructive operations.\n\n## Local development\n\nFrom the repo root:\n\n```bash\nnpm install\nnpm run build --workspace=@savantoai/mcp-server\nSAVANTO_API_KEY=if_sk_… SAVANTO_API_URL=http://localhost:3001 node sdks/mcp/dist/stdio.js\n```\n\nRun the tests:\n\n```bash\nnpm run test --workspace=@savantoai/mcp-server\n```\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n",
  "bytes": 9081,
  "sha": "9af3f32441cab268a1adf861ce095e1a1bfd752ccbc2c285bce4708217401e8a",
  "repo_slug": "savantoai/mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_savantoai_mcp_server_628e85e9/readme"
}