MCP Plugin

Bridge to Model Context Protocol (MCP) servers, enabling the model to interact with external services like Atlassian, GitHub, Slack, and more.

Name	`mcp`
Type	Tool Plugin (Registry-managed)
Tools Provided	Dynamic (discovered from MCP servers)
User Commands	None
Auto-approved	None (requires permission)

Features

Dynamic Tool Discovery: Automatically discovers tools from connected MCP servers
Multi-Server Support: Connect to multiple MCP servers simultaneously
Background Connection: Runs async MCP protocol in background thread
Environment Variable Expansion: Support for ${VAR} syntax in config
Schema Cleaning: Cleans schemas for provider compatibility

How It Works

Plugin reads .mcp.json configuration
Spawns MCP server processes (stdio transport)
Discovers available tools from each server
Exposes discovered tools to the AI model
Routes tool calls to the appropriate MCP server

Basic usage

from jaato import PluginRegistry

registry = PluginRegistry()
registry.discover()

# Expose MCP plugin
# (reads .mcp.json from cwd or home directory)
registry.expose_tool('mcp')

# Check discovered tools
schemas = registry.get_exposed_tool_schemas()
for schema in schemas:
    print(f"- {schema.name}: {schema.description}")

Discovered tools example

From 'Atlassian' server:
  - confluence_search: Search Confluence pages
  - jira_get_issue: Get JIRA issue details
  - jira_create_issue: Create a new JIRA issue

From 'github' server:
  - github_search_repos: Search GitHub repositories
  - github_get_file: Get file contents from repo

Configuration

MCP servers are configured via .mcp.json. The plugin searches for this file in:

./.mcp.json (current working directory)
~/.mcp.json (home directory)

Server Specification

Field	Type	Description
`type`	`string`	Transport type (currently only `"stdio"`)
`command`	`string`	Executable to spawn
`args`	`string[]`	Command line arguments
`env`	`object`	Environment variables

Environment Variable Expansion

Environment variables in the config can reference system env vars using the ${VAR_NAME} syntax.

.mcp.json example

{
  "mcpServers": {
    "Atlassian": {
      "type": "stdio",
      "command": "mcp-atlassian",
      "args": [],
      "env": {
        "ATLASSIAN_URL": "${ATLASSIAN_URL}",
        "ATLASSIAN_USER": "${ATLASSIAN_USER}",
        "ATLASSIAN_TOKEN": "${ATLASSIAN_TOKEN}"
      }
    },
    "github": {
      "type": "stdio",
      "command": "mcp-github",
      "args": ["--org", "my-org"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
      }
    }
  }
}

Tool Execution

When the model invokes an MCP tool, the plugin:

Looks up which server provides the tool
Routes the call to that server's connection
Waits for the response (30 second timeout)
Returns the result to the model

Return Value

Field	Type	Description
`result.tool`	`string`	Name of the tool that was called
`result.isError`	`bool`	Whether the MCP call resulted in error
`result.content`	`string[]`	Text content from the response
`result.structured`	`object`	Structured content if provided
`error`	`string`	Error message if call failed

Example tool call

# Model invokes an MCP tool:
# jira_get_issue(issue_key="PROJ-123")

# Plugin returns:
{
  "result": {
    "tool": "jira_get_issue",
    "isError": false,
    "content": [
      "Issue: PROJ-123\nTitle: Fix login bug\n..."
    ],
    "structured": {
      "key": "PROJ-123",
      "summary": "Fix login bug",
      "status": "In Progress",
      "assignee": "john.doe"
    }
  }
}

# On error:
{
  "error": "Tool 'unknown_tool' not found on any MCP server"
}

Common MCP Servers

Here are some popular MCP servers that work with this plugin:

Server	Package	Capabilities
Atlassian	`mcp-atlassian`	JIRA, Confluence
GitHub	`@anthropic/mcp-github`	Repos, Issues, PRs
Slack	`@anthropic/mcp-slack`	Messages, Channels
Filesystem	`@anthropic/mcp-filesystem`	File operations
PostgreSQL	`mcp-postgres`	Database queries

Installing MCP Servers

MCP servers are typically installed via npm or pip:

npm install -g @anthropic/mcp-github
pip install mcp-atlassian

Full configuration example

{
  "mcpServers": {
    "Atlassian": {
      "type": "stdio",
      "command": "mcp-atlassian",
      "env": {
        "ATLASSIAN_URL": "${ATLASSIAN_URL}",
        "ATLASSIAN_USER": "${ATLASSIAN_USER}",
        "ATLASSIAN_TOKEN": "${ATLASSIAN_TOKEN}"
      }
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y", "@anthropic/mcp-filesystem",
        "--allow-read", "/home/user/projects",
        "--allow-write", "/home/user/projects"
      ]
    }
  }
}

Required environment variables

# Atlassian
export ATLASSIAN_URL="https://company.atlassian.net"
export ATLASSIAN_USER="user@company.com"
export ATLASSIAN_TOKEN="your-api-token"

# GitHub
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

# Slack
export SLACK_BOT_TOKEN="xoxb-xxxxxxxxxxxx"

Troubleshooting

No tools discovered

Verify .mcp.json exists and is valid JSON
Check that MCP server executables are installed and in PATH
Look for error messages in stderr during initialization

Connection errors

Verify environment variables are set correctly
Check MCP server's own logs for auth/connection issues
Try running the MCP server command directly to test

Tool call timeout

Default timeout is 30 seconds
Some MCP operations may take longer
Check MCP server for slow operations or network issues

Schema validation errors

The plugin automatically removes unsupported JSON Schema fields ($schema, $ref, $defs, etc.) for provider compatibility. If you see schema errors, the MCP server may be using unsupported schema features.

Testing MCP server manually

# Test that the MCP server starts correctly
mcp-atlassian

# Should output JSON-RPC messages like:
# {"jsonrpc":"2.0","method":"...","params":...}

# If you see errors, check environment:
env | grep ATLASSIAN

# Check the executable is in PATH:
which mcp-atlassian

Debug output

# The plugin logs connection issues to stderr:

[MCPToolPlugin] Connection error for Atlassian:
  Connection refused - is the server running?

[MCPToolPlugin] Error creating schema for tool_name:
  Unsupported schema format

[Filtered non-JSONRPC]: npm WARN deprecated...
  (harmless - filtering npm noise)