AI Agents (MCP)

Savanto speaks the Model Context Protocol, so AI agents (Claude, ChatGPT, Cursor, Cline, and any other MCP-compatible client) can drive your Savanto workspace by chat. Connect the hosted server in one click over OAuth — no API key to manage — or run @savantoai/mcp-server locally for offline/scripting use.

Instead of clicking through the dashboard to create a workspace, configure a crawl, and tune chat behavior, you describe what you want in plain English and the agent calls the right Savanto tools in sequence.

What the agent can do

The MCP server exposes ~70 tools backed by the Savanto REST API, across these areas:

Category	Tools
Workspaces	`list_workspaces`, `create_workspace`, `update_workspace`, `delete_workspace`, `get_workspace_settings`
Crawl	`start_crawl`, `get_crawl_status`, `get_crawl_history`, `get_crawl_config`, `update_crawl_config`
Products	`upsert_product`, `bulk_upsert_products`, `list_products`, `get_product`, `patch_product`, `delete_product`, `bulk_delete_products`, `search_products`
Posts	`upsert_post`, `bulk_upsert_posts`, `get_post`, `patch_post`, `delete_post`, `bulk_delete_posts`, `search_posts`
Taxonomies	`upsert_taxonomy`, `bulk_upsert_taxonomies`, `list_taxonomies`, `get_taxonomy`, `delete_taxonomy`, `bulk_delete_taxonomies`
Prompts	`upsert_prompt`, `bulk_upsert_prompts`, `list_prompts`, `get_prompt`, `search_prompts`, `delete_prompt`, `bulk_delete_prompts`
Webhooks	`create_webhook`, `list_webhooks`, `get_webhook`, `update_webhook`, `test_webhook`, `get_webhook_stats`, `delete_webhook`
Analytics	`get_search_analytics`, `get_chat_analytics`, `get_feedback_analytics`, `list_feedback`, `search_search_logs`
Conversations	`search_threads`, `get_thread`, `get_thread_messages`, `get_thread_analytics`, `delete_thread`, `bulk_delete_threads`
Settings & widgets	`update_workspace_settings`, `get_chat_widget_config`, `update_chat_widget_config`, `get_search_widget_config`, `update_search_widget_config`, `generate_color_scheme`
Custom domains	`list_custom_domains`, `create_custom_domain`, `update_custom_domain`, `delete_custom_domain`, `generate_domain_config`, `validate_custom_domain`, `test_domain_connection`, `discover_tools`
Chat	`chat`
Diagnostics	`whoami`, `get_tenant_usage`

Tools are scope-gated at startup. When the server boots, it probes /tenant/whoami with your API key and only registers tools your key is actually authorized to use — so an agent is never shown a tool it would receive a 403 for.

Skills (playbooks)

Beyond raw tools, the server registers a handful of MCP prompts ("Skills" in Claude Desktop parlance) that teach the agent how to chain multiple tools together:

onboard-wordpress — provision a workspace, install the plugin, verify the first sync
onboard-shopify — Shopify app onboarding with a merchant walkthrough
configure-chat — tune persona, special instructions, handoff rules
debug-empty-search — diagnose why product search returns no hits
migrate-from-competitor — bulk import from another chat vendor's export

In Claude Desktop, invoke one by typing /onboard-shopify (the list appears under the slash-command menu).

Quick start

There are two ways to connect:

Remote (recommended) — point your client at the hosted endpoint and approve a one-click sign-in. No API key to copy or store.
Local — run the server on your own machine with npx + a secret API key. Good for offline use, scripting, or CI.

Connect remotely (recommended)

Add Savanto as a remote MCP server / custom connector in your client, using this URL:

https://mcp.savanto.ai/mcp

Your client opens the Savanto consent screen — sign in, choose the store to connect, and approve. The tools light up immediately, and no API key ever touches your client.

Claude (claude.ai or Desktop) — add a custom connector and paste the URL.
Cursor — Settings → Model Context Protocol → add a server by URL.
ChatGPT — add a custom connector with the URL.

Any MCP client that supports remote servers with OAuth works the same way.

Manage or disconnect connections anytime from dashboard/connected-apps. Each connection is scoped to the store you chose, uses short-lived, automatically rotating credentials, and can be revoked instantly — disconnecting cuts access off right away.

Run locally (npx + secret key)

Prefer to run the server on your own machine? Use the stdio build with a secret API key.

1. Create a secret API key

Go to dashboard/api-keys and create a secret key (starts with if_sk_…). Label it something memorable like "Claude Desktop" so you can revoke it cleanly later.

Publishable keys (if_pk_…) are client-side and cannot provision workspaces — the server will refuse to start with one.

2. Configure your MCP client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or %APPDATA%\Claude\claude_desktop_config.json on Windows) and add:

{
  "mcpServers": {
    "savanto": {
      "command": "npx",
      "args": ["-y", "@savantoai/mcp-server"],
      "env": {
        "SAVANTO_API_KEY": "if_sk_your_key_here"
      }
    }
  }
}

Restart Claude Desktop — you should see a hammer/tool icon in the message bar.

Cursor

Settings → Features → Model Context Protocol → Add new MCP server:

{
  "savanto": {
    "command": "npx",
    "args": ["-y", "@savantoai/mcp-server"],
    "env": { "SAVANTO_API_KEY": "if_sk_your_key_here" }
  }
}

Cline / Roo (VS Code)

Add to the extension's MCP config:

{
  "mcpServers": {
    "savanto": {
      "command": "npx",
      "args": ["-y", "@savantoai/mcp-server"],
      "env": { "SAVANTO_API_KEY": "if_sk_your_key_here" }
    }
  }
}

OpenAI Agents SDK (Python)

from mcp import StdioServerParameters

server = StdioServerParameters(
    command="npx",
    args=["-y", "@savantoai/mcp-server"],
    env={"SAVANTO_API_KEY": "if_sk_your_key_here"},
)

Local MCP Inspector (debugging)

npx @modelcontextprotocol/inspector npx @savantoai/mcp-server

The Inspector gives you a web UI to list tools, invoke them directly, and watch request/response payloads — useful for verifying your key is wired up correctly before handing the server to an agent.

Example conversations

Once the server is registered, try:

"Create a new Savanto workspace called acme-store for the Shopify platform, then start a crawl of https://acme.test and let me know when it finishes."

"Search my acme-store workspace for products matching 'waterproof hiking boots' in the $100–$200 range."

"Tune the chat persona for acme-store to be enthusiastic about outdoor adventure — and tell me what changed."

The agent will pick the right tools automatically based on your intent.

Environment variables

Variable	Default	Purpose
`SAVANTO_API_KEY`	(required)	Your secret API key (`if_sk_…`).
`SAVANTO_API_URL`	`https://api.savanto.ai`	Override for staging or local development.

Security

Remote connections use OAuth 2.1 (with PKCE). The token your client receives is scoped to a single store, short-lived and auto-rotated, and revocable from connected-apps — no long-lived API key is ever exposed to the client.
Local: separate keys per agent / machine. Revoke one without affecting the others. The API Keys page shows last-used timestamps.
Keys are passed via environment variables, never logged. The server prints a one-line identity banner to stderr on startup (tenant id + scope list) — no secrets.
The server runs over stdio. It never opens a network port and only talks to the Savanto API host you point it at.
delete_workspace requires an explicit confirm: true parameter — a safety gate against hallucinated destructive operations.

Roadmap

Remote (hosted, OAuth) and local (stdio) transports are both live. Still on the roadmap:

Savanto CLI (npx savanto) — thin wrapper around the same tool handlers for scripting without an agent.
Additional tools — memories, threads inspection, prompt editing, widget config.

File issues and feature requests on the repo or email support@savanto.ai.