> ## Documentation Index > Fetch the complete documentation index at: https://docs.svantic.com/llms.txt > Use this file to discover all available pages before exploring further. # Tools and capabilities # Tools & Capabilities Svantic has three ways to give agents tools: **capabilities** (your code, running on your machine), **MCP servers** (tool processes running alongside Svantic), and **builtin tools** (pre-built integrations shipped with the SDK). *** ## Capabilities A capability is a function your agent exposes to the AI. You define it with `define_capability` and it becomes invocable by the mesh — just like any built-in tool. ```typescript theme={null} agent.define_capability({ name: 'extract_invoice_data', description: 'Extract structured data from an invoice PDF', parameters: { type: 'object', properties: { file_path: { type: 'string', description: 'Path to the invoice PDF' }, fields: { type: 'array', items: { type: 'string' }, description: 'Specific fields to extract (e.g. ["total", "date", "vendor"])', }, }, required: ['file_path'], }, handler: async (args) => { const data = await invoice_parser.extract(args.file_path as string, args.fields as string[]); return data; }, }); ``` | Field | Type | Required | Description | | ------------- | --------- | -------- | --------------------------------------------- | | `name` | string | Yes | Unique capability name (snake\_case) | | `description` | string | Yes | What this capability does — the AI reads this | | `parameters` | object | Yes | JSON Schema defining expected inputs | | `tags` | string\[] | No | Tags for categorization | | `handler` | function | Yes | Async function that executes locally | ### How Capabilities Become AI-Callable 1. Svantic reads your agent card (including skills with parameters) 2. For each skill, Svantic creates a **capability proxy** 3. When the AI invokes the capability, the proxy sends an A2A task to your agent 4. Your handler receives the arguments and returns the result The AI doesn't know the capability runs on a different machine. ### Bidirectional Execution Capabilities execute on **your machine**, not on the server. This is a foundational architectural decision. Bidirectional capability execution: Svantic sends A2A task, agent executes locally, returns result The agent never sends credentials or raw data. It receives a structured request, executes locally, and returns just the result. This is what makes Svantic usable in regulated industries — the mesh sees capability names and results, not the underlying data. **Why it matters:** * **Data sovereignty** — data never leaves your environment * **Security** — credentials stay on the machine that owns them * **Network topology** — works behind firewalls, VPNs, air-gapped environments (outbound only) * **Scale** — execution is distributed across your agents; Svantic handles reasoning ### Design Guidelines **Do:** * Be atomic — one capability, one action * Write descriptions the AI can understand * Use JSON Schema with descriptions on every property * Return structured data with clear field names * Handle errors gracefully with clear messages **Don't:** * Bundle multiple operations into one capability * Expose raw SQL — wrap queries in specific capabilities * Return HTML — return structured data * Skip descriptions on parameters *** ## MCP Servers MCP (Model Context Protocol) servers are tool processes that Svantic spawns and manages. They're ideal for general-purpose utilities like browser automation, filesystem access, or code search. ### MCP vs. Capabilities | | Capabilities (A2A) | MCP Servers | | -------------------- | ---------------------------------------- | ----------------------------------------- | | **Where code runs** | Your machine, your process | Svantic's machine, child process | | **Protocol** | A2A JSON-RPC 2.0 over HTTP | MCP over stdio | | **Data sovereignty** | Full | None — tools run inside Svantic's env | | **Best for** | Business logic, databases, internal APIs | Browser automation, filesystem, dev tools | **Rule of thumb:** If the tool needs your database, credentials, or internal state → **capability**. If it's a general-purpose utility → **MCP**. ### Adding MCP Servers **`settings.json` (permanent):** ```json theme={null} { "mcpServers": { "chrome-devtools": { "command": "npx", "args": ["chrome-devtools-mcp@0.12.1", "--headless=false"] }, "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"] } } } ``` **REST API (runtime, in-memory — cleared on restart):** ```bash theme={null} curl -X POST https://api.svantic.com/config/mcp/register \ -H "Content-Type: application/json" \ -d '{ "servers": { "my-custom-tools": { "command": "node", "args": ["./path/to/my-mcp-server.js"] } } }' ``` **Terminal client:** Use `/mcp add` for an interactive wizard, `/mcp list` to see all servers, `/mcp sync` to re-push after a server restart. ### Common MCP Servers | Server | Package | Purpose | | ------------------- | ----------------------------------------- | ---------------------------------- | | **Chrome DevTools** | `chrome-devtools-mcp` | Browser automation via CDP | | **Filesystem** | `@modelcontextprotocol/server-filesystem` | Read/write files | | **Ripgrep** | `mcp-ripgrep` | Fast regex search across codebases | | **Playwright** | `@anthropic/mcp-playwright` | Full browser automation | | **GitHub** | `@modelcontextprotocol/server-github` | GitHub API | Any npm package that speaks the MCP protocol works with Svantic — just add it to `settings.json`. ### Writing a Custom MCP Server ```typescript theme={null} import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; const server = new Server( { name: 'my-tools', version: '1.0.0' }, { capabilities: { tools: {} } }, ); server.setRequestHandler('tools/list', async () => ({ tools: [{ name: 'analyze_logs', description: 'Parse and analyze application log files', inputSchema: { type: 'object', properties: { log_path: { type: 'string', description: 'Path to log file' }, severity: { type: 'string', description: 'Filter: error, warn, info' }, }, required: ['log_path'], }, }], })); server.setRequestHandler('tools/call', async (request) => { const { name, arguments: args } = request.params; if (name === 'analyze_logs') { const result = await parse_logs(args.log_path, args.severity); return { content: [{ type: 'text', text: JSON.stringify(result) }] }; } return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true }; }); const transport = new StdioServerTransport(); await server.connect(transport); ``` *** ## Builtin Tools The SDK ships with **25 production-ready tools** across 7 domains. Enable them in `settings.json`: ```json theme={null} { "builtinDomains": ["github", "jira", "slack", "shell"], "credentials": { "GITHUB_TOKEN": "ghp_...", "JIRA_BASE_URL": "https://yourcompany.atlassian.net", "JIRA_EMAIL": "you@company.com", "JIRA_API_TOKEN": "ATATT3x...", "SLACK_BOT_TOKEN": "xoxb-..." } } ``` ### Available Domains | Domain | Tools | Credentials | | ------------- | -------------------------------------------------- | --------------------------------------------------------- | | **GitHub** | 6 (list PRs, get PR, diff, create, review, merge) | `GITHUB_TOKEN` | | **Bitbucket** | 6 (list PRs, get PR, diff, create, comment, merge) | `BITBUCKET_USERNAME`, `BITBUCKET_APP_PASSWORD` | | **Jira** | 4 (get issue, create, transition, comment) | `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` | | **Zendesk** | 5 (list tickets, get, create, update, comment) | `ZENDESK_SUBDOMAIN`, `ZENDESK_EMAIL`, `ZENDESK_API_TOKEN` | | **Slack** | 1 (send message) | `SLACK_BOT_TOKEN` | | **Shell** | 1 (execute any command) | None — guarded by policies | | **Datadog** | 2 (get alerts, query metrics) | `DATADOG_API_KEY`, `DATADOG_APP_KEY` | ### Shell Tool A general-purpose command execution tool that replaces the need for individual `git`, `kubectl`, `docker`, or `terraform` wrappers. The agent constructs the command; `shell_exec` runs it locally. ```json theme={null} { "command": "git status", "cwd": "/my/repo", "timeout_ms": 30000 } ``` Returns `{ "stdout": "...", "stderr": "...", "exit_code": 0 }`. ### Programmatic Usage ```typescript theme={null} import { BuiltinToolLoader } from '@svantic/sdk'; const loader = new BuiltinToolLoader(); const result = await loader.load_domains(['github', 'jira', 'shell']); ``` The SDK also exports `HttpHelper` for building custom tools that call HTTP APIs.