ARCANA
Back to Blog

Architecture

MCP and Tools: How Arcana Extends Its Capabilities

Jun 22, 2026 Architecture

Arcana's tool system has two layers: built-in tools that ship with the agent, and MCP tools that extend it. Understanding how they interact is key to getting the most out of Arcana.

Tools are how the agent interacts with the world. Without tools, an agent is just a chatbot. With tools, it can read your codebase, run commands, query databases, control browsers, and integrate with any service that exposes a tool interface. The tool system is the bridge between the agent's reasoning and the real world.

Arcana's two-layer architecture means you get a solid set of built-in tools for free, and you can extend the agent with any MCP-compatible tool server. This is the difference between a tool that does what its developers imagined and a tool that does what you need.

Built-In Tools

Arcana ships with core tools for the most common agent operations: reading files, writing files, searching code, running shell commands, and web requests. These are optimized, tested, and always available.

MCP Servers

The Model Context Protocol is a standard for exposing tools over stdio. Any MCP-compatible server can add tools to Arcana. Configure them in your Arcana config file:

  • Linux / macOS: ~/.arcana/config.json
  • Windows: %USERPROFILE%\.arcana\config.json
{
  "mcp": {
    "agent-browser": {
      "command": "npx",
      "args": ["-y", "@anthropic/agent-browser"]
    },
    "my-custom-server": {
      "command": "node",
      "args": ["./my-server.js"],
      "env": { "API_KEY": "..." }
    }
  }
}

Tool Discovery

When Arcana starts, it connects to all configured MCP servers and discovers their available tools. The agent sees the full tool set: built-in tools plus MCP tools, all available through the same interface.

# See all configured MCP servers
arcana mcp list

# Add a new MCP server
arcana mcp add agent-browser

Tool Selection

The agent decides which tool to use based on the task. It does not differentiate between built-in and MCP tools. If you configure an MCP server that provides a "search database" tool, the agent will use it when appropriate alongside built-in tools like "read file" or "run command."

Custom MCP Servers

Writing an MCP server is straightforward. The protocol is documented and the SDKs are available for TypeScript, Python, and Go. A minimal MCP server exposes a list of tools with JSON Schema input definitions.

This means you can expose your internal APIs, databases, or services as tools that the agent can use. The agent does not need to know the implementation details; it just sees the tool schema.

Security

MCP servers run as separate processes. They have whatever access you give them. Arcana's permission system can gate MCP tool usage separately from built-in tools, so you can allow file reads but require approval for database queries, for example.

The key security principle is that MCP servers are untrusted by default. They can do whatever their process permissions allow, but Arcana's permission system sits between the agent and the server. The agent requests a tool call; the permission system evaluates whether that call is allowed; only then does the request reach the MCP server.

This means you can configure fine-grained policies: allow browser screenshots but block JavaScript execution, allow database reads but require approval for writes, allow web fetches to known domains but gate requests to unknown ones. The permission system does not care whether a tool is built-in or MCP; it evaluates every tool call against the same policy.

Related Reading