Skip to main content

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 & 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. 
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;
	},
});
FieldTypeRequiredDescription
namestringYesUnique capability name (snake_case)
descriptionstringYesWhat this capability does — the AI reads this
parametersobjectYesJSON Schema defining expected inputs
tagsstring[]NoTags for categorization
handlerfunctionYesAsync 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 runsYour machine, your processSvantic’s machine, child process
ProtocolA2A JSON-RPC 2.0 over HTTPMCP over stdio
Data sovereigntyFullNone — tools run inside Svantic’s env
Best forBusiness logic, databases, internal APIsBrowser 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): 
{
	"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): 
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

ServerPackagePurpose
Chrome DevToolschrome-devtools-mcpBrowser automation via CDP
Filesystem@modelcontextprotocol/server-filesystemRead/write files
Ripgrepmcp-ripgrepFast regex search across codebases
Playwright@anthropic/mcp-playwrightFull browser automation
GitHub@modelcontextprotocol/server-githubGitHub API
Any npm package that speaks the MCP protocol works with Svantic — just add it to settings.json.

​
Writing a Custom MCP Server

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: 
{
	"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

DomainToolsCredentials
GitHub6 (list PRs, get PR, diff, create, review, merge)GITHUB_TOKEN
Bitbucket6 (list PRs, get PR, diff, create, comment, merge)BITBUCKET_USERNAME, BITBUCKET_APP_PASSWORD
Jira4 (get issue, create, transition, comment)JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN
Zendesk5 (list tickets, get, create, update, comment)ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, ZENDESK_API_TOKEN
Slack1 (send message)SLACK_BOT_TOKEN
Shell1 (execute any command)None — guarded by policies
Datadog2 (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. 
{ "command": "git status", "cwd": "/my/repo", "timeout_ms": 30000 }
Returns { "stdout": "...", "stderr": "...", "exit_code": 0 }.

​
Programmatic Usage

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.