AI Agents (MCP)

Savanto ships a local Model Context Protocol server — @savantoai/mcp-server — that lets AI agents (Claude, ChatGPT, Cursor, Cline, and any other MCP-compatible client) drive your Savanto workspace by chat.

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 a curated set of tools backed by the Savanto REST API:

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
Content	upsert_product, upsert_post, search_products, search_posts
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

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

• 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

This is a v1 local-stdio release. On the roadmap:

• Remote MCP transport (HTTPS) — connect directly from a cloud agent without running npx locally. Targeting OAuth flow for multi-tenant agents.
• 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.