MCP server for managing TsAgent agents. Provides tools to create, configure, and manage agents including rules, references, tools, providers, and MCP servers.

This package provides an MCP server that exposes a comprehensive set of tools for managing TsAgent agents. All tools use an agentTarget parameter to identify which agent to operate on (specified as the file path to a .yaml agent file).

npm install -g @tsagent/agent-mcp

tsagent-agent-mcp [--debug|-d]

Options:

• --debug or -d: Enable debug mode for verbose logging

Note: Unlike meta-mcp, this server doesn't require an agent path at startup. Agents are loaded on-demand when tools are called with an agentTarget parameter.

• agent_list: List all available agents. If basePath is provided, recursively searches for .yaml or .yml agent files. Otherwise, returns agents from the internal registry.
• agent_get_info: Get detailed information about a specific agent
• agent_create: Create a new agent
• agent_delete: Delete an agent and all its associated files (requires confirm: true)
• agent_clone: Clone an existing agent to a new location

• agent_get_settings: Get all settings for an agent (currently returns empty object - agent API doesn't provide a method to retrieve all settings)
• agent_set_setting: Set a single setting value
• agent_get_system_prompt: Get the system prompt for an agent
• agent_set_system_prompt: Set the system prompt for an agent
• agent_get_metadata: Get agent metadata
• agent_update_metadata: Update agent metadata

• agent_list_rules: List all rules for an agent
• agent_get_rule: Get a specific rule by name
• agent_add_rule: Add a new rule to an agent
• agent_update_rule: Update an existing rule
• agent_delete_rule: Delete a rule from an agent

• agent_list_references: List all references for an agent
• agent_get_reference: Get a specific reference by name
• agent_add_reference: Add a new reference to an agent
• agent_update_reference: Update an existing reference
• agent_delete_reference: Delete a reference from an agent

• agent_list_tools: List all exported tools for an agent
• agent_get_tool: Get a specific tool by name
• agent_add_tool: Add a new exported tool to an agent
• agent_update_tool: Update an existing tool
• agent_delete_tool: Delete a tool from an agent

• agent_list_providers: List all installed and available providers
• agent_get_provider_config: Get configuration for a specific provider
• agent_install_provider: Install and configure a provider
• agent_update_provider: Update provider configuration
• agent_uninstall_provider: Uninstall a provider from an agent
• agent_validate_provider_config: Validate a provider configuration without installing it

• agent_list_mcp_servers: List all MCP servers configured for an agent
• agent_get_mcp_server: Get configuration for a specific MCP server
• agent_add_mcp_server: Add a new MCP server configuration
• agent_update_mcp_server: Update an existing MCP server configuration
• agent_delete_mcp_server: Remove an MCP server from an agent

All tools that operate on an agent require an agentTarget parameter. This parameter should be the file path to a .yaml or .yml agent file.

Examples:

• ./agents/my-agent.yaml
• /absolute/path/to/agent.yaml

The server maintains an internal registry of loaded agents to avoid repeated file I/O. Agents are loaded on-demand when first accessed.

Agent Metadata (agent_get_metadata / agent_update_metadata):

• Purpose: Describes the agent's identity, capabilities, and mode
• Contains:
  • Identity: name, description, version
  • Presentation: iconUrl, documentationUrl, provider info
  • Exported capabilities: skills (for A2A agents), tools (for agents exporting tools)
  • Timestamps: created, lastAccessed
• Usage: Used to describe what the agent is and what it can do

Agent Settings (agent_get_settings / agent_set_setting):

• Purpose: Runtime configuration parameters for agent behavior
• Contains:
  • Model settings: temperature, topP, mostRecentModel
  • Conversation limits: maxChatTurns, maxOutputTokens
  • Context settings: contextTopK, contextTopN, contextIncludeScore
  • UI settings: theme
  • Tool permissions: toolPermission
• Usage: Used to configure how the agent behaves during conversations
• Note: agent_get_settings currently returns an empty object because the agent API doesn't provide a method to retrieve all settings at once without knowing all possible keys. Use agent_set_setting to set individual settings.

{
  "name": "agent_create",
  "arguments": {
    "agentPath": "./agents/my-new-agent.yaml",
    "name": "My New Agent",
    "description": "A helpful assistant",
    "autonomous": false,
    "initialPrompt": "You are a helpful AI assistant."
  }
}

{
  "name": "agent_add_rule",
  "arguments": {
    "agentTarget": "./agents/my-agent.yaml",
    "rule": {
      "name": "be-polite",
      "description": "Always be polite",
      "text": "Always use polite language and be respectful.",
      "priorityLevel": 1,
      "include": "always"
    }
  }
}

{
  "name": "agent_install_provider",
  "arguments": {
    "agentTarget": "./agents/my-agent.yaml",
    "providerType": "openai",
    "config": {
      "OPENAI_API_KEY": "op://vault/item/field"
    }
  }
}

This package includes BaseMCPServer, a reusable abstract base class for building MCP servers. It handles:

• MCP protocol communication
• Tool registration and routing
• JSON Schema validation of tool arguments
• Error handling and structured responses

Subclasses implement:

• toolHandlersArray: Array of tool definitions with co-located handlers
• serverInfo: Server name and version
• serverInstructions: Server description

See the source code in src/base-mcp-server.ts for details on extending it for your own MCP servers.

The server maintains an in-memory registry of loaded agents keyed by normalized file paths. This allows:

• Fast access to already-loaded agents
• Lazy loading of agents on first access
• Automatic path normalization

All tools return structured JSON responses. On error:

{
  "success": false,
  "error": {
    "code": "TOOL_EXECUTION_ERROR",
    "message": "Error description"
  }
}

On success, tools return their specific result format.

This MCP server provides management tools (prefixed with agent_*) that operate on other agents. This is distinct from an agent's own tools (like add_rule, create_reference) which operate on the agent itself without needing an agentTarget parameter.

cd packages/agent-mcp
npm install
npm run build

This will compile TypeScript to JavaScript in the dist/ directory.

npm run dev

node dist/index.js

Or using the binary:

npm link  # Link the package globally (if you want)
tsagent-agent-mcp

1. Build the package:

   cd packages/agent-mcp
   npm run build

2. Create or update your Claude Desktop MCP config (usually at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

   {
     "mcpServers": {
       "agent-management": {
         "command": "node",
         "args": [
           "/absolute/path/to/tsagent/packages/agent-mcp/dist/index.js"
         ]
       }
     }
   }

3. Restart Claude Desktop to load the new MCP server

4. Test the tools - The agent management tools should now be available in Claude Desktop

You can use the MCP Inspector to test the server:

# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

# Run the inspector with the agent-mcp server
npx @modelcontextprotocol/inspector \
  node /path/to/tsagent/packages/agent-mcp/dist/index.js

• "Failed to load agent" error: Make sure the agent path is correct and the agent exists
• "Agent is not configured as a Tools agent": Tool management tools require the agent to have exported tools (non-empty tools array in metadata)
• Build errors: Make sure @tsagent/core is built first:

  cd ../agent-api
  npm run build
  cd ../agent-mcp
  npm install ../agent-api  # Link local package
  npm run build

• Agent Management MCP Design - Full design document
• TsAgent Core API - Core agent API documentation