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;
	},
});

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

Svantic reads your agent card (including skills with parameters)
For each skill, Svantic creates a capability proxy
When the AI invokes the capability, the proxy sends an A2A task to your agent
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):

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

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

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

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.

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

​Tools & Capabilities

​Capabilities

​How Capabilities Become AI-Callable

​Bidirectional Execution

​Design Guidelines

​MCP Servers

​MCP vs. Capabilities

​Adding MCP Servers

​Common MCP Servers

​Writing a Custom MCP Server

​Builtin Tools

​Available Domains

​Shell Tool

​Programmatic Usage