Connect MCP Servers

The Model Context Protocol (MCP) is an open standard for exposing tools, resources, and prompts to AI agents through a uniform interface. Instead of hand-writing a handler for every capability, you can point the Syntic Agent SDK at an MCP server and its entire tool surface becomes available to Amara. This is how you plug the agent into things that already exist — a filesystem server, a database connector, an issue tracker, or your own internal service — and reuse them across projects and languages.

Because MCP is a protocol rather than a library, the same server works with any compliant client. Many capabilities are distributed as ready-made servers, and you can wrap your own systems behind one when you want them shared broadly rather than embedded in a single agent.

Adding a server

Servers connect over stdio (a local subprocess) or HTTP (a networked endpoint). List them in the mcpServers option; the SDK handles discovery and routing tool calls to the right server.

import { query } from "@syntic/agent-sdk";
 
for await (const msg of query({
  prompt: "Open the latest issues and summarize the top three.",
  options: {
    mcpServers: {
      tracker: {
        command: "npx",
        args: ["-y", "@example/mcp-tracker"],
        env: { TRACKER_TOKEN: process.env.TRACKER_TOKEN! },
      },
      docs: { type: "http", url: "https://mcp.internal.example.com" },
    },
  },
})) {
  if (msg.type === "result") console.log(msg.result);
}

from syntic_agent_sdk import query
 
async for msg in query(
    prompt="Open the latest issues and summarize the top three.",
    options={
        "mcp_servers": {
            "tracker": {
                "command": "npx",
                "args": ["-y", "@example/mcp-tracker"],
                "env": {"TRACKER_TOKEN": os.environ["TRACKER_TOKEN"]},
            },
            "docs": {"type": "http", "url": "https://mcp.internal.example.com"},
        }
    },
):
    if msg.type == "result":
        print(msg.result)

Working with server tools

Tools from an MCP server are namespaced by the key you assign the server, so a search tool on the docs server appears distinctly from a search on another. They participate in the same permission and approval flow as built-in and custom tools, so you can allow, deny, or gate them individually. When a server exposes many tools, combine MCP with tool search so the agent discovers what it needs on demand instead of loading every definition into context up front. Treat server credentials like any other secret — pass them through the environment and scope them narrowly.