Task Agent MCP Server

A flexible MCP server that lets you create specialized AI agents as individual tools in Claude. Each agent appears as its own tool with custom prompts, models, and capabilities.

v4.1.0 - New CLI flags: --tools, --name, --disallowed-tools, --mcp-config

🎯 What is This?

Task Agent MCP Server turns markdown files into specialized AI agents. Each agent:

• Appears as a separate tool in Claude
• Has its own system prompt and personality
• Can use specific Claude models (opus, sonnet, haiku)
• Maintains conversation context (optional)
• Access specific directories and resources

🚀 Quick Install (2 Steps)

Step 1: Install the package

# Requires Python 3.11 or higher
python3.11 -m pip install task-agents-mcp

Step 2: Add to Claude Code

claude mcp add task-agent task-agent -s project

That's it! ✅ The server comes with an example agent template to get you started.

💬 How to Use

Your First Agent

The package includes task-agents/example-agent.md as a template. Try it:

"Use example_agent to explain how task agents work"

Creating Your Own Agents

1. Copy the example template:

   cp task-agents/example-agent.md task-agents/my-agent.md
   

2. Edit my-agent.md to customize:

   • Agent name and description
   • System prompt (the agent's personality and instructions)
   • Tools it can use
   • Model (opus for complex reasoning, sonnet for implementation)

3. Use your new agent:

   "Use my_agent to [your task]"
   

📝 Agent Configuration

Each agent is a markdown file with YAML frontmatter:

---
# REQUIRED FIELDS
agent-name: My Assistant
description: Brief description of what this agent does
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
cwd: .

# OPTIONAL FIELDS
optional:
  # Enable session memory (remembers context between calls)
  resume-session: true 10  # Remember last 10 exchanges

  # Additional directories the agent can access
  resource_dirs: ./docs, ./data

  # Tools to deny (agent won't have access to these)
  disallowed-tools: WebSearch, WebFetch

  # Give the agent access to external MCP servers
  mcp-config: ./mcp-servers.json
---

System-prompt:
You are a specialized assistant that...
[Your detailed instructions here]

Available Tools

Agents can use any combination of these tools:

• File Operations: Read, Write, Edit, MultiEdit
• Search: Glob, Grep, LS
• Shell: Bash, BashOutput, KillBash
• Web: WebSearch, WebFetch
• Other: TodoWrite, NotebookEdit, Task

Available Models

• opus: Best for complex reasoning, planning, analysis
• sonnet: Best for implementation, coding, execution
• haiku: Fast responses for simple tasks

🖥️ Also Works with Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "task-agent": {
      "command": "task-agent",
      "env": {
        "TASK_AGENTS_PATH": "/path/to/your/agents"
      }
    }
  }
}

💡 Example Agents

Code Review Agent

---
agent-name: Code Reviewer
description: Reviews code for bugs, performance, and best practices
tools: Read, Grep, Glob
model: opus
cwd: .
---

System-prompt:
You are an expert code reviewer. Focus on:
- Finding bugs and potential issues
- Suggesting performance improvements
- Ensuring code follows best practices
- Checking for security vulnerabilities

DevOps Agent

---
agent-name: DevOps Engineer
description: Manages deployments, CI/CD, and infrastructure
tools: Read, Write, Edit, Bash
model: sonnet
cwd: .
optional:
  resume-session: true 5
---

System-prompt:
You are a DevOps engineer specializing in:
- Docker and Kubernetes configurations
- CI/CD pipeline setup
- Infrastructure as Code
- Deployment automation

🔧 Advanced Features

Session Management

Enable conversation memory for multi-step tasks:

optional:
  resume-session: true      # 5 exchanges (default)
  resume-session: true 10   # 10 exchanges  
  resume-session: false     # Disabled

Perfect for:

• Multi-step debugging sessions
• Feature implementation across multiple files
• Extended code reviews
• Iterative optimization

Resource Directories

Give agents access to additional directories:

optional:
  resource_dirs: ./templates, ./data, ./scripts

Disallowed Tools

Deny specific tools from an agent:

optional:
  disallowed-tools: Bash, WebSearch, WebFetch

MCP Server Access

Give agents access to external MCP servers (e.g., databases, APIs):

optional:
  mcp-config: ./mcp-servers.json

The MCP config file follows the standard format:

{
  "my-db": {
    "type": "stdio",
    "command": "db-mcp-server",
    "args": ["--connection", "postgres://..."]
  }
}

When mcp-config is set, --strict-mcp-config is also applied so the agent only uses its configured MCP servers.

Working Directory

Set where the agent operates from:

cwd: .                    # Project root (default)
cwd: ./src               # Specific subdirectory
cwd: /absolute/path      # Absolute path

📦 Requirements

• Python 3.11 or higher
• Claude Code CLI (Download here)

🛠️ Troubleshooting

No agents loaded

• Check that your .md files are in the task-agents/ directory
• Verify the YAML frontmatter is valid
• Ensure all required fields are present

Agent not appearing

• Agent names with spaces become underscores in tool names
• "Code Reviewer" becomes code_reviewer tool
• Check server logs: /tmp/task_agents_server.log

Python version issues

# Check your Python version
python3 --version

# If less than 3.11, install Python 3.11
# macOS: brew install python@3.11
# Ubuntu: sudo apt install python3.11

📚 Project Structure

your-project/
├── task-agents/           # Your agent configurations
│   ├── example-agent.md   # Template/example agent
│   ├── my-agent.md        # Your custom agents
│   └── ...
└── .mcp.json             # MCP configuration (auto-created)

🔗 Links

• GitHub: https://github.com/vredrick/task-agent
• PyPI: https://pypi.org/project/task-agents-mcp/
• MCP Protocol: https://modelcontextprotocol.io/

📄 License

MIT License - See LICENSE file for details