MCP servers

The Model Context Protocol (MCP) is an open standard for connecting AI tools to external data sources. IsonForge supports stdio-based MCP servers configured in settings.json.

Configuration

Add servers under mcpServers in ~/.isonforge/settings.json (user) or <cwd>/.isonforge/settings.json (project):

{
  "mcpServers": {
    "github": {
      "command": "mcp-github",
      "args": ["--repo", "myorg/myrepo"],
      "env": {"GITHUB_TOKEN": "$GITHUB_TOKEN"}
    },
    "postgres": {
      "command": "uvx",
      "args": ["mcp-server-postgres", "--dsn", "$POSTGRES_DSN"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/notes"]
    }
  }
}

Each server entry:

Tool namespacing

Tools from MCP servers appear to the agent as mcp__<server>__<tool>. So a github server with a create_issue tool becomes mcp__github__create_issue.

Lifecycle

Permissions

MCP tools follow the active permission mode. They aren't allowlisted by default.

In auto mode, MCP tools fall under "ask" by default - the agent asks before each invocation.

Whitelist a server's tools en masse with a wildcard rule in ~/.isonforge/permissions.json:

{
  "rules": [
    {"tool": "mcp__github__*", "action": "allow"},
    {"tool": "mcp__postgres__*", "action": "ask"}
  ]
}

Inspect

/mcp

Lists each server with: name, connected/error state, tool count, tool names. Use this to verify a server is loaded.

For deeper inspection, run with --verbose - server stdout/stderr is captured to the verbose log.

Compatible servers

IsonForge implements the MCP client side of the spec. Any server that speaks MCP over stdio works.

Popular servers:

The community list lives at github.com/modelcontextprotocol/servers.

Authoring a server

The IsonForge CLI bundles @modelcontextprotocol/sdk so any node script can register as an MCP server. Minimal example:

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: 'fetch_status',
    description: 'Get current production status',
    inputSchema: { type: 'object', properties: {} },
  }],
}));

server.setRequestHandler('tools/call', async (req) => {
  if (req.params.name === 'fetch_status') {
    return { content: [{ type: 'text', text: 'all systems green' }] };
  }
  throw new Error('unknown tool');
});

await server.connect(new StdioServerTransport());

Save as my-server.js and add to settings.json:

{
  "mcpServers": {
    "my-tools": {"command": "node", "args": ["/path/to/my-server.js"]}
  }
}

Best practices