Agency Agents MCP Server

An MCP (Model Context Protocol) server that gives GitHub Copilot access to 160+ specialist AI agent personas and 1,400+ specialized skills. Once installed, you can ask Copilot to "be a backend architect" or "activate the security engineer" (agents), or "use brainstorming" or "activate TDD" (skills) and it will adopt that specialist's full personality, expertise, and methodology for the rest of the conversation. Works with JetBrains Rider, IntelliJ, and VS Code on Linux, macOS, and Windows. Deployable as a Docker container with Azure DevOps pipeline support.

⚡ Quick Start for Developers: See the Quick Reference Guide for the top 10 most useful skills, ready-to-use commands, and real-world workflows.

---

What You Get

Eleven tools are exposed to Copilot's agent mode:

Agent Tools

Tool	What it does
get_agent_index	Ultra-cheap agent index: slug + name only
list_agents	List all installed personas, optionally filtered by category
activate_agent	Load a persona in summary, compact, or full mode
search_agents	Search agents by keyword
get_shared_instructions	Load shared instructions in summary, compact, or full mode

Agent categories include: engineering, design, marketing, testing, sales, product, academic, support, game-development, specialized, project-management, paid-media, spatial-computing, and more.

Skill Tools

Tool	What it does
get_skill_index	Ultra-cheap skill index: id + category + name only
list_skills	List all available skills, optionally filtered by category
activate_skill	Load a skill in summary, compact, or full mode
search_skills	Search skills by keyword
get_skill_categories	View all skill categories with counts

Skill categories include: ai-ml, backend, frontend, security, testing, automation, design, marketing, data, workflow, devops, and many more.

System Tools

Tool	What it does
healthz	RPC-based health check endpoint for Kubernetes probes (see HEALTHZ-RPC.md)

Cheapest Discovery Path

For the lowest token cost in your IDE:

1. Use get_agent_index or get_skill_index first
2. Use search_* or list_* only if the index is not enough
3. Load summary, then compact, then full only if needed

Example calls:

{ "name": "get_agent_index", "arguments": {} }
{ "name": "get_skill_index", "arguments": {} }
{ "name": "activate_agent", "arguments": { "query": "security-engineer", "mode": "summary" } }
{ "name": "activate_skill", "arguments": { "query": "brainstorming", "mode": "summary" } }

Both index tools support category, offset, limit, and all: true.

Prerequisites

Local Development

• Node.js >= 18 (check with node -v)
• npm (ships with Node)
• git
• GitHub Copilot plugin installed in your IDE with an active subscription

Docker Deployment

• Docker (check with docker -v)
• Docker Compose (optional, for local development)

---

Docker Deployment (Recommended for Production)

Quick Start with Docker

```bash git clone https://github.com/Regtransfers/agency-agents-mcp.git cd agency-agents-mcp docker build -t agency-agents-mcp:latest . docker run -it agency-agents-mcp:latest ```

Using Docker Compose

```bash git clone https://github.com/Regtransfers/agency-agents-mcp.git cd agency-agents-mcp docker-compose up --build ```

Azure Container Registry Deployment

The project includes Azure DevOps pipelines that automatically build and push Docker images to Azure Container Registry on every commit to `main`:

• Pipeline: `azure-pipelines.yml`
• Container Registry: `bluemountain.azurecr.io`
• Image Name: `agency-agents-mcp` The pipeline is configured to run on the `BlueMountain-PROD` agent pool.

---

Quick Setup (Connect to Hosted Server)

No installation required! Connect your IDE directly to the hosted MCP server.

One-Time Setup

1. Download the bridge script: ```bash

Linux/macOS - save to ~/.local/bin

mkdir -p ~/.local/bin curl -o ~/.local/bin/mcp-http-bridge https://raw.githubusercontent.com/Regtransfers/agency-agents-mcp/main/mcp-http-bridge.mjs chmod +x ~/.local/bin/mcp-http-bridge ```

2. Configure your IDE:

Rider 2025.3+ (GitHub Copilot MCP - Linux/macOS):

Rider 2025.3+ requires a wrapper script AND multiple config files. Here's the complete setup:

```bash

Step 1: Create the wrapper script

cat > ~/.local/bin/mcp-agency-agents << 'EOF' #!/bin/bash export MCP_URL="https://agency-agents-mcp.regtransfers.dev" exec ~/.local/bin/mcp-http-bridge "$@" EOF chmod +x ~/.local/bin/mcp-agency-agents

Step 2: Create the GitHub Copilot MCP server definition

mkdir -p ~/.config/github-copilot/intellij cat > ~/.config/github-copilot/intellij/mcp.json << 'EOF' { "servers": { "agency-agents": { "type": "stdio", "command": "/home/$USER/.local/bin/mcp-agency-agents" } } } EOF

Step 3: CRITICAL - Tell GitHub Copilot where to find MCP config

This adds the mcpConfigPath to github-copilot.xml

Note: Rider must be CLOSED for this to work!

cat > ~/.config/JetBrains/Rider2025.3/options/github-copilot.xml << 'EOF' <application> <component name="github-copilot"> <option name="mcpConfigPath" value="/home/$USER/.config/github-copilot/intellij/mcp.json" /> <option name="signinNotificationShown" value="true" /> <option name="terminalRulesVersion" value="1" /> <mcpSamplingAllowedModels> <option value="claude-sonnet-4.5" /> <option value="gpt-4.1" /> <option value="gpt-5.4" /> <option value="gpt-5.4-mini" /> </mcpSamplingAllowedModels> </component> </application> EOF ```

CRITICAL: You MUST completely close and restart Rider for the configuration to load!

Verify the setup works:

# Test the wrapper script manually
~/.local/bin/mcp-agency-agents <<< '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# Should return JSON with 11 tools (including get_agent_index and get_skill_index)

Rider/IntelliJ (Older Versions - Linux/macOS): ```bash mkdir -p ~/.config/github-copilot/intellij && cat > ~/.config/github-copilot/intellij/mcp.json << 'EOF' { "servers": { "agency-agents": { "type": "stdio", "command": "/home/$USER/.local/bin/mcp-http-bridge", "env": { "MCP_URL": "https://agency-agents-mcp.regtransfers.dev" } } } } EOF ```

VS Code (All Platforms - Easiest Method):

1. Open VS Code
2. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
3. Type: MCP: Open User Configuration
4. Add the server configuration:

```json { "servers": { "Regtransfers-Agents": { "url": "https://agency-agents-mcp.regtransfers.dev/", "type": "http" } }, "inputs": [] } ```

5. Save the file and restart VS Code
6. Done! No bridge script needed for VS Code with HTTP servers.

VS Code (Linux/macOS - Alternative Method with Bridge): ```bash mkdir -p ~/.config/github-copilot/vscode && cat > ~/.config/github-copilot/vscode/mcp.json << 'EOF' { "servers": { "agency-agents": { "type": "stdio", "command": "/home/$USER/.local/bin/mcp-http-bridge", "env": { "MCP_URL": "https://agency-agents-mcp.regtransfers.dev" } } } } EOF ```

Windows (PowerShell): ```powershell

Download bridge

$bridgeDir = "$env:LOCALAPPDATA\mcp-bridge" New-Item -ItemType Directory -Force -Path $bridgeDir | Out-Null Invoke-WebRequest -Uri "https://raw.githubusercontent.com/Regtransfers/agency-agents-mcp/main/mcp-http-bridge.mjs" -OutFile "$bridgeDir\mcp-http-bridge.mjs"

Configure Rider

$configDir = "$env:APPDATA\github-copilot\intellij" # or 'vscode' for VS Code New-Item -ItemType Directory -Force -Path $configDir | Out-Null @" { "servers": { "agency-agents": { "type": "stdio", "command": "node", "args": ["$bridgeDir\mcp-http-bridge.mjs"], "env": { "MCP_URL": "https://agency-agents-mcp.regtransfers.dev" } } } } "@ | Set-Content "$configDir\mcp.json" ```

3. Restart Rider (CRITICAL)

Close Rider completely and reopen it. GitHub Copilot only loads MCP configs at startup.

4. Verify the setup:

Open GitHub Copilot Chat and test: ``` List available agents ```

You should see 144 agent personas loaded from the remote server.

⚠️ IMPORTANT: When you switch to a different project in Rider, you MUST start a NEW Copilot conversation for MCP tools to reload. GitHub Copilot doesn't refresh MCP tools in existing conversations when you change projects.

Quick fix: Click the "+" icon in Copilot Chat to start a fresh conversation, then try List available agents again.

If you don't see the agents:

1. Start a NEW conversation (click + in Copilot Chat) - this is the most common fix

2. Check the config file exists: ```bash cat ~/.config/github-copilot/intellij/mcp.json ```

3. Test the bridge manually: ```bash MCP_URL="https://agency-agents-mcp.regtransfers.dev" ~/.local/bin/mcp-http-bridge

   Paste this and press Enter:

   {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}

   Should return: {"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":...

   ```

4. Check Rider logs: ```bash tail -f ~/.cache/JetBrains/Rider2025.3/log/idea.log | grep -i "mcp|agency" ``` Look for "MCP Extension Service" or "agency-agents" mentions

---

Local Development (Advanced)

1. Clone the repository

```bash git clone https://github.com/Regtransfers/agency-agents-mcp.git cd agency-agents-mcp ``` The repository includes:

• 160+ agent personas in ./agents/
• 1,400+ specialized skills in ./skills/
• Shared instructions (clean code standards) in ./shared-instructions/
• The MCP server (server.mjs) configured to use local folders

2. Install dependencies

```bash npm install --production ```

3. Verify it starts

```bash node server.mjs

Should hang (waiting for stdin). Ctrl+C to stop.

```

4. Register with your IDE

The config file must use fully resolved absolute paths — it does not expand `~`, `$HOME`, or `%USERPROFILE%`.

Important: Use the absolute path to `node`, not just `node`. IDEs do not inherit your shell's PATH, so a bare `node` command will silently fail — especially if node was installed via nvm, fnm, Homebrew, etc.

Find yours with: `which node` (Linux/macOS) or `(Get-Command node).Source` (PowerShell). Run these commands from the project directory. They will automatically detect your node path and project path. JetBrains Rider / IntelliJ (Linux / macOS): ```bash NODE_BIN="$(readlink -f "$(which node)" 2>/dev/null || which node)" && \ PROJECT_PATH="$(pwd)" && \ mkdir -p ~/.config/github-copilot/intellij && cat > ~/.config/github-copilot/intellij/mcp.json << EOF { "servers": { "agency-agents": { "type": "stdio", "command": "$NODE_BIN", "args": ["$PROJECT_PATH/server.mjs"] } } } EOF ``` VS Code (Linux / macOS): ```bash NODE_BIN="$(readlink -f "$(which node)" 2>/dev/null || which node)" && \ PROJECT_PATH="$(pwd)" && \ mkdir -p ~/.config/github-copilot/vscode && cat > ~/.config/github-copilot/vscode/mcp.json << EOF { "servers": { "agency-agents": { "type": "stdio", "command": "$NODE_BIN", "args": ["$PROJECT_PATH/server.mjs"] } } } EOF ``` Windows (PowerShell): ```powershell $nodeBin = ((Get-Command node).Source -replace '\\','/') $projectPath = (Get-Location).Path -replace '\\','/' $dir = "$env:APPDATA\github-copilot\intellij" # change 'intellij' to 'vscode' for VS Code New-Item -ItemType Directory -Force -Path $dir | Out-Null @" { "servers": { "agency-agents": { "type": "stdio", "command": "$nodeBin", "args": ["$projectPath/server.mjs"] } } } "@ | Set-Content "$dir\mcp.json"

The server automatically uses the `./agents/`, `./skills/`, and `./shared-instructions/` folders from the project directory. You can override with environment variables `AGENTS_DIR`, `SKILLS_DIR`, and `SHARED_INSTRUCTIONS_DIR` if needed.
### 5. Restart the IDE
Close and reopen your IDE. The Copilot plugin reads \`mcp.json\` at startup and launches the server automatically.
---
## Usage
Open Copilot Chat in **agent mode** and try:

### Working with Agents

List available agents

Activate the backend architect agent and review my API design

Search for agents about security

List engineering agents

### Working with Skills

List available skills

Activate the brainstorming skill

Search for skills about testing

Show me all skill categories

List skills in the ai-ml category

When you activate an agent or skill, the AI adopts those instructions for the rest of the conversation. Start a new chat to reset.

> **📘 New to Skills?** See the [**Skills Guide**](SKILLS-GUIDE.md) for a comprehensive introduction to the 1,400+ available skills, including categories, best practices, and usage examples.
> 
> **⚡ Development Teams?** Check out the [**Quick Reference**](QUICK-REFERENCE.md) for the top 10 skills and real-world workflow examples tailored for feature development, testing, and infrastructure deployment.

---
## For Development Teams: Top 10 Essential Skills

These skills are specifically selected for teams building features, writing tests, and deploying infrastructure:

### 🎯 **Feature Development**
1. **`brainstorming`** - Design features before coding

Use the brainstorming skill to help me design a user authentication system

2. **`test-driven-development`** - Write tests first (TDD workflow)

Activate TDD skill and help me add payment processing with Stripe

3. **`code-review-excellence`** - Conduct thorough code reviews

Activate code-review-excellence and review this PR for the new API endpoints

### 🔧 **API Development**
4. **`api-design-principles`** - REST and GraphQL API design

Use api-design-principles skill to design a REST API for our inventory system

5. **`api-security-testing`** - API vulnerability testing

Activate api-security-testing and audit our authentication endpoints

### 🧪 **Testing & Quality**
6. **`e2e-testing`** - End-to-end test workflows

Use e2e-testing skill to create Playwright tests for our checkout flow

7. **`systematic-debugging`** - Debug methodically, not randomly

Activate systematic-debugging and help me fix this race condition in our queue processor

### 🚀 **Infrastructure & Deployment**
8. **`kubernetes-deployment`** - K8s best practices and Flux CD

Use kubernetes-deployment skill to create a deployment manifest for our new microservice

9. **`gitops-workflow`** - GitOps and Flux patterns

Activate gitops-workflow and help me set up Flux CD for our staging environment

10. **`ci-cd-automation`** - Pipeline automation workflows
 ```
 Use ci-cd-automation skill to create a GitHub Actions workflow for our API tests
 ```

### 📋 **Real-World Workflow Examples**

**Building a new API feature:**

1. Use brainstorming skill to design the API
2. Activate backend-architect agent + api-design-principles skill
3. Use test-driven-development skill to implement with tests
4. Activate code-review-excellence skill before merging
5. Use kubernetes-deployment skill to create K8s manifests

**Debugging a production issue:**

Activate the senior-developer agent, then use systematic-debugging skill to help me trace this timeout in our payment service

**Setting up new infrastructure:**

Use kubernetes-deployment and gitops-workflow skills to help me deploy our new service with Flux CD

**Security audit before release:**

Activate security-engineer agent + api-security-testing skill to audit our new authentication endpoints

### 💡 **Combining Agents + Skills**

The real power comes from combining agent personas with skill methodologies:

Activate the backend-architect agent, then use the api-design-principles and test-driven-development skills to help me build a new payment API with comprehensive tests

This gives you:
- **Agent expertise** (backend architecture knowledge)
- **Skill methodologies** (API design + TDD workflows)
- **Systematic approach** (following proven patterns)

### 🔍 **Discover More Skills**

Search for skills about terraform # Infrastructure as Code Search for skills about docker # Containerization Search for skills about monitoring # Observability Search for skills about graphql # GraphQL APIs List skills in the devops category # All DevOps skills

---
## Adding Custom Agents
Drop a Markdown file into \`./agents/\` in the project directory. The format is:
\`\`\`markdown
---
name: My Custom Agent
description: One-line summary of what this agent does
---
# My Custom Agent
You are **My Custom Agent**. You specialise in...
(full instructions and personality here)
\`\`\`
Only \`name\` and \`description\` from the frontmatter are used by the server. Everything below the frontmatter is the persona body that gets sent to the AI.
Restart the IDE or rebuild the Docker image after adding new agents.
---
## Shared Instructions (Clean Code & More)
The server supports **shared instructions** — Markdown files that are automatically prepended to every agent activation. This is how you enforce baseline standards (clean code, security guidelines, project conventions, etc.) across all 160+ agent personas.
A default \`clean-code.md\` is included in \`./shared-instructions/\`. It covers naming, SOLID, DRY/KISS/YAGNI, testing, error handling, and more.
### Where they live
Instructions are stored in \`./shared-instructions/\` in the project directory.
### Customising
- **Edit** \`./shared-instructions/clean-code.md\` to match your team's standards.
- **Add** more \`.md\` files (e.g. \`project-conventions.md\`, \`security-policy.md\`) — all files are loaded and concatenated alphabetically.
- **Remove** any file you don't want.
- Restart the IDE or rebuild the Docker image after changes.
### Viewing in chat
Ask Copilot:
\`\`\`
Show me the shared instructions
\`\`\`
This calls the \`get_shared_instructions\` tool and shows exactly what baseline rules are being applied.
---
## Updating Agents
Agents are included in the repository. To get the latest:
\`\`\`bash
git pull origin main
\`\`\`
Then restart the IDE or rebuild the Docker image.
---
## Uninstall
To remove the IDE integration, simply delete the \`"agency-agents"\` block from your \`mcp.json\` file and restart the IDE.
For Docker deployments, stop and remove the container:
\`\`\`bash
docker stop agency-agents-mcp
docker rm agency-agents-mcp
# Optional: remove the image
docker rmi agency-agents-mcp:latest
\`\`\`
---
## Directory Layout
\`\`\`
agency-agents-mcp/
├── agents/                                   # 160+ agent persona .md files
│   ├── engineering-backend-architect.md
│   ├── engineering-code-reviewer.md
│   ├── engineering-security-engineer.md
│   ├── design-ux-architect.md
│   └── ... (160+ files)
├── skills/                                   # 1,400+ specialized skills
│   ├── brainstorming/
│   │   └── SKILL.md
│   ├── test-driven-development/
│   │   └── SKILL.md
│   ├── security-audit/
│   │   └── SKILL.md
│   └── ... (1,400+ skills)
├── shared-instructions/                      # Shared standards applied to ALL agents
│   └── clean-code.md
├── skills_index.json                         # Skills metadata index
├── build/
│   └── azure-devops/
│       ├── azure-pipelines.yml               # Pipeline template
│       └── buildimages.yaml                  # Build job definitions
├── server.mjs                                # MCP server (stdio protocol)
├── http-wrapper.mjs                          # HTTP wrapper for production
├── mcp-http-bridge.mjs                       # HTTP-to-stdio bridge for IDE
├── package.json
├── package-lock.json
├── Dockerfile                                # Docker image definition
├── docker-compose.yml                        # Docker Compose config
├── .dockerignore                             # Docker build exclusions
├── azure-pipelines.yml                       # Main Azure pipeline
└── node_modules/
IDE Config Files:
~/.config/JetBrains/Rider2025.3/mcp_config.json      # Rider 2025.3+ (Linux/macOS)
~/.local/bin/mcp-agency-agents                       # Rider 2025.3+ wrapper script
~/.config/github-copilot/intellij/mcp.json           # Rider/IntelliJ older (Linux/macOS)
~/.config/github-copilot/vscode/mcp.json             # VS Code (Linux/macOS)
%APPDATA%\\github-copilot\\intellij\\mcp.json           # Rider/IntelliJ (Windows)
%APPDATA%\\github-copilot\\vscode\\mcp.json             # VS Code (Windows)
\`\`\`
---
## Troubleshooting

### Quick Fixes (Most Common Issues)

| Symptom | Fix |
|---|---|
| **🔥 Switched projects - MCP tools disappeared** | **START A NEW COPILOT CONVERSATION** (click the "+" icon in Copilot Chat). GitHub Copilot loads MCP tools per-conversation. When you switch projects, existing conversations keep stale tools. Fresh conversation = fresh MCP tools. This is the #1 most common issue. |
| **"I don't have access to those MCP tools"** | **First:** Start a NEW Copilot conversation (click +). **Then** if still broken: Restart Rider completely and check the MCP logs (see below). |
| **⚠️ MCP Plugin Disabled in Rider** | **CRITICAL:** Check if `~/.config/JetBrains/Rider*/disabled_plugins.txt` contains `com.intellij.mcpServer`. If it does, the MCP plugin is disabled! Remove that line or delete the file, then restart Rider. This is a common gotcha that completely breaks MCP integration. |
| **Rider 2025.3+ / 2026.1+ - Tools not loading** | You need BOTH config files AND a wrapper script. See detailed steps below. Also verify MCP plugin is not disabled (see above). |

### Detailed Troubleshooting for Rider 2025.3+

#### Step 1: Verify All Required Files Exist

**⚠️ CRITICAL: Check if MCP Plugin is Disabled**

Rider/IntelliJ can disable plugins, which completely breaks MCP integration. Check this FIRST:

```bash
# Check if MCP plugin is disabled (Rider 2025.3)
cat ~/.config/JetBrains/Rider2025.3/disabled_plugins.txt 2>/dev/null | grep mcpServer

# For Rider 2026.1
cat ~/.config/JetBrains/Rider2026.1/disabled_plugins.txt 2>/dev/null | grep mcpServer

If you see com.intellij.mcpServer in the output:

• The MCP plugin is DISABLED and MCP will NOT work!
• Fix it: Remove that line from the file, or delete the entire disabled_plugins.txt file
• Then: Restart Rider completely

Verify the plugin is enabled:

# After restarting Rider, check the logs
grep "MCP Extension Service started successfully" ~/.cache/JetBrains/Rider*/log/idea.log

# Should show: "MCP Extension Service started successfully"

Check the wrapper script exists and is executable:

ls -l ~/.local/bin/mcp-agency-agents
# Should show: -rwxr-xr-x (executable permissions)

If missing or not executable:

cat > ~/.local/bin/mcp-agency-agents << 'EOF'
#!/bin/bash
export MCP_URL="https://agency-agents-mcp.regtransfers.dev"
exec ~/.local/bin/mcp-http-bridge "$@"
EOF
chmod +x ~/.local/bin/mcp-agency-agents

Check the bridge script exists:

ls -l ~/.local/bin/mcp-http-bridge
# Should show the bridge file

If missing:

curl -o ~/.local/bin/mcp-http-bridge https://raw.githubusercontent.com/Regtransfers/agency-agents-mcp/main/mcp-http-bridge.mjs
chmod +x ~/.local/bin/mcp-http-bridge

Step 2: Verify Configuration Files

Check GitHub Copilot's MCP config path (CRITICAL for Rider 2025.3+):

cat ~/.config/JetBrains/Rider2025.3/options/github-copilot.xml

MUST contain this line:

<option name="mcpConfigPath" value="/home/YOUR_USERNAME/.config/github-copilot/intellij/mcp.json" />

If missing, add it (close Rider first!):

# Replace YOUR_USERNAME with your actual username!
cat > ~/.config/JetBrains/Rider2025.3/options/github-copilot.xml << 'EOF'
<application>
  <component name="github-copilot">
    <option name="mcpConfigPath" value="/home/$USER/.config/github-copilot/intellij/mcp.json" />
    <option name="signinNotificationShown" value="true" />
    <option name="terminalRulesVersion" value="1" />
    <mcpSamplingAllowedModels>
      <option value="claude-sonnet-4.5" />
      <option value="gpt-4.1" />
      <option value="gpt-5.4" />
      <option value="gpt-5.4-mini" />
    </mcpSamplingAllowedModels>
  </component>
</application>
EOF

Check the MCP server definition file:

cat ~/.config/github-copilot/intellij/mcp.json

Should contain:

{
    "servers": {
        "agency-agents": {
            "type": "stdio",
            "command": "/home/YOUR_USERNAME/.local/bin/mcp-agency-agents"
        }
    }
}

Check Rider's MCP config:

cat ~/.config/JetBrains/Rider2025.3/mcp_config.json

Should contain (replace $USER with your actual username):

{
  "mcpServers": {
    "agency-agents": {
      "command": "/home/YOUR_USERNAME/.local/bin/mcp-agency-agents",
      "args": []
    }
  }
}

Check Rider's MCP server status:

cat ~/.config/JetBrains/Rider2025.3/options/llm.mcpServers.xml

Should show:

<option name="enabled" value="true" />
<option name="name" value="agency-agents" />

Step 3: Test the Wrapper Script Manually

This is the BEST way to verify everything works:

~/.local/bin/mcp-agency-agents <<< '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Expected output:

{"result":{"tools":[{"name":"list_agents",...},{"name":"activate_agent",...},...]},"jsonrpc":"2.0","id":1}

You should see 11 tools: list_agents, activate_agent, search_agents, get_shared_instructions, list_skills, activate_skill, search_skills, get_skill_categories, healthz, get_agent_index, get_skill_index.

If you get an error:

• Check the MCP_URL is set correctly in the wrapper
• Verify the bridge script has execute permissions
• Test the bridge directly: MCP_URL="https://agency-agents-mcp.regtransfers.dev" ~/.local/bin/mcp-http-bridge and send the same JSON

Step 4: Check Rider MCP Logs

View the MCP server logs:

tail -50 ~/.cache/JetBrains/Rider2025.3/log/mcp/agency-agents.log

What to look for:

• Server started - Good! Server is launching
• "method":"initialize" - Good! Rider is connecting
• "method":"tools/list" - Good! Rider is requesting tools
• Server stopped - Normal when idle (saves resources)

If log file doesn't exist: Rider hasn't tried to start the MCP server yet. Verify your config files above.

If log shows errors: Share the error message for specific troubleshooting.

Step 5: Check Rider General Logs

Search for MCP-related errors:

tail -100 ~/.cache/JetBrains/Rider2025.3/log/idea.log | grep -i "mcp\|agency"

Look for:

• McpToolsetHost being initialized
• Any error messages about MCP servers
• Connection failures

Step 6: Verify the Remote Server is Running

Test the hosted MCP server directly:

curl -X POST https://agency-agents-mcp.regtransfers.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Should return: JSON with 11 tools

If this fails: The remote server may be down. Check server status or run locally instead.

Other Common Issues

Symptom	Fix
MCP server doesn't start / tools not showing	Open `mcp.json` and check that `"command"` is the absolute path to node (e.g. `/usr/bin/node`, not just `node`). IDEs don't inherit your shell PATH. Run `which node` to find it.
Copilot doesn't show the agent tools	Restart the IDE. Verify `mcp.json` exists in the correct directory and uses absolute paths.
Server crashes on startup	Run `node server.mjs` from the project directory manually to see the error. Usually a missing `npm install`.
"No agents installed" response	Check `./agents/` has `.md` files. Verify you're running from the correct directory.
`node: command not found`	Ensure Node >= 18 is installed and on your `PATH`. Use the absolute path in `mcp.json`.
Works in VS Code but not Rider (or vice versa)	Each IDE has its own `mcp.json` path. Make sure you created the config in the right directory.
Already have other MCP servers in `mcp.json`	Merge the `"agency-agents"` block into your existing `servers` object rather than replacing the file.
Docker build fails	Ensure Docker is installed and running. Check that all files are present in the build context.
Pipeline fails in Azure DevOps	Verify the agent pool name (`BlueMountain-PROD`) and service connection ID match your Azure setup.

Still Not Working?

Create a diagnostic report:

echo "=== Wrapper Script ===" && \
cat ~/.local/bin/mcp-agency-agents && \
echo -e "\n=== Bridge Script ===" && \
ls -lh ~/.local/bin/mcp-http-bridge && \
echo -e "\n=== GitHub Copilot Config (CRITICAL) ===" && \
cat ~/.config/JetBrains/Rider2025.3/options/github-copilot.xml && \
echo -e "\n=== GitHub Copilot MCP Servers ===" && \
cat ~/.config/github-copilot/intellij/mcp.json && \
echo -e "\n=== Rider MCP Config ===" && \
cat ~/.config/JetBrains/Rider2025.3/mcp_config.json && \
echo -e "\n=== MCP Server Status ===" && \
cat ~/.config/JetBrains/Rider2025.3/options/llm.mcpServers.xml && \
echo -e "\n=== Manual Test ===" && \
~/.local/bin/mcp-agency-agents <<< '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' 2>&1 | head -20

Share the output when asking for help.

---

Common Gotchas & Pitfalls

🔴 MCP Plugin Disabled in Rider

The Problem: Rider/IntelliJ can disable plugins through the disabled_plugins.txt file. If com.intellij.mcpServer is in this file, the MCP plugin will not load at all, and you'll get NO MCP tools despite having perfect configuration files.

Symptoms:

• All config files are correct
• Manual tests of the MCP server work fine
• Rider logs show NO mention of "MCP Extension Service" or "mcpServer"
• GitHub Copilot works, but MCP tools never appear

How to Check:

# Check if the plugin is disabled
cat ~/.config/JetBrains/Rider*/disabled_plugins.txt | grep mcpServer

The Fix:

# Option 1: Remove the disabled plugin entry
# Edit the file and remove the line containing com.intellij.mcpServer

# Option 2: Delete the entire file (if you don't have other disabled plugins)
rm ~/.config/JetBrains/Rider*/disabled_plugins.txt

# Then: COMPLETELY restart Rider (close all windows)

Verify it's fixed:

grep "MCP Extension Service started successfully" ~/.cache/JetBrains/Rider*/log/idea.log
# Should show: MCP Extension Service started successfully

🔴 Switching Projects Breaks MCP Tools

The Problem: GitHub Copilot loads MCP tools per-conversation, not per-project. When you switch projects, existing conversations retain the MCP tools from the PREVIOUS project.

The Fix: Click the "+" icon in Copilot Chat to start a NEW conversation. The new conversation will load MCP tools for the current project.

🔴 Rider Ignores Config Changes

The Problem: Rider only loads mcp.json and related configs at startup. Editing them while Rider is running has no effect.

The Fix: COMPLETELY close Rider (all windows) and restart after making any config changes.

🔴 Relative Paths Don't Work

The Problem: MCP configs don't expand ~, $HOME, %USERPROFILE%, or environment variables.

The Fix: Always use fully resolved absolute paths in all config files:

• ✅ /home/aaron/.local/bin/mcp-agency-agents
• ❌ ~/.local/bin/mcp-agency-agents
• ❌ $HOME/.local/bin/mcp-agency-agents

🔴 Multiple Rider Versions Installed

The Problem: If you have Rider 2025.3 AND Rider 2026.1 installed, make sure you're editing the config for the version you're actually running.

The Fix:

# Check which Rider version is running
ps aux | grep -i rider

# Edit configs for the CORRECT version:
# Rider 2025.3: ~/.config/JetBrains/Rider2025.3/
# Rider 2026.1: ~/.config/JetBrains/Rider2026.1/

---

How It Works

1. The Copilot plugin reads `mcp.json` at startup and spawns `node server.mjs` as a child process.
2. The server communicates with Copilot over stdin/stdout using the Model Context Protocol.
3. When you ask Copilot to list or activate an agent, it calls the MCP tool.
4. The server reads the matching `.md` file from `./agents/` and returns the persona text, prepended with any shared instructions from `./shared-instructions/`.
5. Copilot adopts those instructions (shared standards + agent persona) for the remainder of the conversation. The server is stateless. It reads all agent files once at startup and serves them from memory. No network calls, no external dependencies at runtime.

Docker Deployment

When deployed as a Docker container:

1. The Dockerfile packages the entire application including all agent definitions.
2. The Azure DevOps pipeline automatically builds and tags images on every commit.
3. Images are pushed to Azure Container Registry (`bluemountain.azurecr.io`).
4. The container can be deployed to any Docker-compatible environment.

---

Documentation

Quick References

• Quick Reference ⭐ - Start here! One-page cheat sheet with top 10 skills, ready-to-use commands, and real-world workflows for development teams
• Skills Guide - Comprehensive guide to all 1,400+ skills, categories, and best practices
• Skills Integration Summary - Technical implementation summary and integration details
• Changelog - Version history and release notes

Key Topics

• Agents - See "Working with Agents" section above
• Skills - See "For Development Teams: Top 10 Essential Skills" section above
• Installation - See "Local Development (IDE Integration)" section above
• Docker - See "Docker Deployment" section above
• Troubleshooting - See "Troubleshooting" section below

---

Credits

Agent personas sourced from msitarzewski/agency-agents. Skills sourced from sickn33/antigravity-awesome-skills. MCP server built on the @modelcontextprotocol/sdk.

Licence

MIT