Skip to main content

​
What You’ll Learn

Practical integration workflows combining custom subagents, rules, and MCP servers for real-world development scenarios.

​
Integration Methods

MethodBest ForConfiguration
Custom SubagentsAI-powered specialized tasks~/.verdent/subagents/*.md
Rules (AGENTS.md)Team standards and behaviorProject root AGENTS.md
MCP ServersProtocol-compliant external tools.mcp.json (project root)
Philosophy: Combine methods to create comprehensive workflows tailored to your needs.

​
Common Integration Patterns

​
Database Development Workflow

Stack: Migration Reviewer Subagent + AGENTS.md Standards + PostgreSQL MCP Server Subagent: 
---
name: migration-reviewer
description: Reviews database migrations for safety
---
Checks: Destructive operations, reversibility, indexing, blocking operations
AGENTS.md: 
## Database Standards
- All migrations reviewed by @migration-reviewer
- Test on staging before production
- Include rollback procedures
MCP: PostgreSQL server for query execution, schema inspection, migration validation Workflow: Write migration → @migration-reviewer validates → MCP tests on staging → PR documentation

​
API Development with Security

Stack: Security Auditor + AGENTS.md Rules + Custom API Testing Tool Components:
  • Subagent: @api-security-auditor - Input validation, SQL injection, auth, rate limiting
  • Rules: All endpoints require security review, rate limiting on public APIs
  • External Tools: Automated endpoint testing and security scans via custom integration
Result: Automatic security review before PR approval.
API testing and security scanning tools can be integrated via custom MCP server implementations or other integration methods depending on your tooling.

​
Frontend Accessibility

Stack: Accessibility Auditor + WCAG Rules + Lighthouse Integration Workflow: 
Create component → @a11y-auditor reviews → Lighthouse tests accessibility → Rules enforce >90 score
Lighthouse and other accessibility tools can be integrated through custom MCP servers or CI/CD pipeline integration depending on your workflow.

​
MCP Configuration Examples

​
Understanding MCP

Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. MCP servers are executables that implement the protocol—they’re not database connections or API endpoints, but programs that run and communicate via JSON-RPC 2.0. Key Concepts:
  • MCP Servers: Executables (Node.js packages, Python scripts, etc.) that implement the MCP protocol
  • Configuration: Tells Verdent how to start the server (command + args)
  • Communication: Servers handle their own business logic (queries, API calls, etc.)

​
Basic Setup

Location: .mcp.json in project root 
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/myapp_dev"
      ]
    }
  }
}
Explanation:
  • mcpServers - Required top-level key for MCP configuration
  • command - Executable to run (typically npx for Node.js packages)
  • args - Arguments passed to the command (package name, connection strings, etc.)
  • env - Environment variables for authentication/configuration

​
Multi-Environment

{
  "mcpServers": {
    "postgres-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DEV_DATABASE_URL}"
      ]
    },
    "postgres-staging": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${STAGING_DATABASE_URL}"
      ]
    },
    "postgres-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${PROD_DATABASE_URL}"
      ]
    }
  }
}
Best Practice: Use environment variables for connection strings to keep credentials secure. MCP servers handle read-only behavior internally based on their implementation—consult specific server documentation for access control options.
Learn More About MCP:

​
Workspace Integration

​
Project-Specific Configuration

Setup:
  1. Store in project root: .mcp.json
  2. Commit to version control for team sharing
  3. Team members automatically use project MCP servers
Microservices Example: 
{
  "mcpServers": {
    "users-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/users"
      ]
    },
    "orders-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5433/orders"
      ]
    }
  }
}
For additional services like Kafka, you would need a compatible MCP server implementation. The official MCP server registry at mcp.so/servers lists available community servers.

​
Team Collaboration

​
Shared AGENTS.md Standards

Commit to version control for team-wide consistency: 
# AGENTS.md

## Code Review Process
- Run @code-reviewer before PR
- Address all security warnings
- Minimum 80% test coverage

## Integration Requirements
- @migration-reviewer for database changes
- @api-security-auditor for new endpoints
- @a11y-auditor for UI components

## MCP Servers
- Use postgres-staging MCP server for queries
- Never use postgres-prod MCP server for exploratory queries
Benefits: Consistent behavior, enforced standards, automatic quality gates.

​
Multi-Agent Coordination

​
Complex Feature Workflow

Example: New payment endpoint 
1. Developer request → 2. Main agent generates code →
3. @api-security-auditor reviews security →
4. @migration-reviewer validates schema →
5. MCP tests on staging →
6. Main agent generates tests and PR
Result: Fully reviewed endpoint with security and database best practices applied.

​
Integration Best Practices

​
Progressive Adoption

Phase 1: Basic rules 
## Code Standards
- Use TypeScript strict mode
- Run tests before commit
Phase 2: Add specialized subagent 
## Code Review
- Run @security-reviewer before PR
Phase 3: Integrate MCP 
## Database Access
- Use MCP postgres-staging for queries

​
Strategic Combinations

CombinationPurposeExample
Rules + SubagentsRules define when, subagents analyzeAGENTS.md: “Review with @security-reviewer”
Rules + MCPRules specify which servers, MCP accessesAGENTS.md: “Use db-staging only”
Subagents + MCPSubagent uses MCP for external dataSecurity auditor queries API endpoints

​
Team Documentation Best Practices

When documenting integrations for your team, include:
  • Custom Subagents: List each subagent’s name, purpose, and when to invoke it
  • AGENTS.md Rules: Document rules with rationale explaining the “why” behind each standard
  • MCP Servers: Describe each server’s purpose, access level (read-only/write), and when to use it
  • Integration Workflows: Provide example workflows showing how components work together
  • Troubleshooting: Document common issues specific to your setup and their solutions
Commit integration documentation alongside your .mcp.json and AGENTS.md files so new team members can quickly understand your setup.

​
Troubleshooting

  • Subagent Issues
  • AGENTS.md Issues
  • MCP Server Issues
Problem: Subagent not invoking when expectedCheck:Location: File exists at ~/.verdent/subagents/[name].mdYAML Frontmatter: Valid syntax with required name and description fieldsInvocation Policy: Matches usage (strict requires explicit @-mention)Description: Agent description accurately describes when the subagent should be usedRestart: Try restarting Verdent to reload subagent definitions
Common Causes:
  • Typo in subagent file name or @-mention
  • Invalid YAML syntax in frontmatter
  • Subagent description doesn’t match task context

​
See Also

Extensibility Guide

Complete extension methods overview

MCP Integration

Model Context Protocol details