# MCP Integration (/docs/verdent-manager/configuration/mcp)

> Extend Verdent with Model Context Protocol servers and plugins



## What is MCP (Model Context Protocol)? [#what-is-mcp-model-context-protocol]

Model Context Protocol (MCP) is an integration system that extends Verdent's capabilities by connecting to external tools, data sources, and services.

**Core Concept:**
MCP enables Verdent to interact with systems beyond its built-in tool set, allowing seamless integration with:

* External APIs and web services
* Database systems
* Cloud platforms (AWS, Azure, GCP)
* Project management tools
* CI/CD pipelines
* Custom internal tools

**Architecture:**
MCP servers act as bridges between Verdent and external systems. Each MCP server exposes specific capabilities that Verdent can invoke during coding sessions, similar to built-in tools like `file_read` or `bash`.

**Configuration Storage:**
MCP server configurations are stored in `~/.verdent/mcp.json` and managed through the Settings menu.

***

## Benefits of MCP Integration [#benefits-of-mcp-integration]

### Extended Capabilities [#extended-capabilities]

**Access External Systems:**
Connect Verdent to tools and services not available through built-in functionality. Query databases, interact with cloud services, or integrate project-specific APIs without leaving your coding workflow.

**Custom Tool Development:**
Create MCP servers tailored to your project's unique requirements. Build specialized integrations for internal tools, proprietary APIs, or domain-specific systems.

### Interoperability [#interoperability]

**Ecosystem Leverage:**
Tap into the growing MCP ecosystem. Community-developed MCP servers provide pre-built integrations for popular tools and services.

**Standardized Protocol:**
MCP provides a consistent interface for tool integration, ensuring new capabilities integrate smoothly with Verdent's existing tool system.

### Workflow Automation [#workflow-automation]

**Seamless Integration:**
MCP servers become part of Verdent's tool set. The agent automatically uses MCP tools when appropriate, or you can explicitly invoke them for specific tasks.

**Context-Aware Operations:**
MCP integrations understand your codebase context, enabling intelligent interactions with external systems based on current development state.

***

## Setting Up MCP Servers [#setting-up-mcp-servers]

### Configuration Process [#configuration-process]

**Access MCP Settings:**

1. Open Settings menu in Verdent
2. Navigate to **MCP Servers** section
3. View or modify `~/.verdent/mcp.json` configuration

**Configuration File:**
MCP servers are configured through the `~/.verdent/mcp.json` file, which defines server connections, authentication, and integration parameters. See the **MCP Configuration** section below for the full schema.

### Configuration Management [#configuration-management]

**Adding Servers:**
Configure new MCP servers by adding entries to `mcp.json` with connection details and authentication credentials.

**Multiple Servers:**
Verdent supports multiple concurrent MCP servers, allowing integration with several external systems simultaneously.

**Testing Connections:**
Validate MCP server configurations to ensure successful connections before using them in development workflows.

### Server Status [#server-status]

Monitor connection status in the MCP settings panel:

| Status      | Description                              |
| ----------- | ---------------------------------------- |
| **Success** | Server connected and tools available     |
| **Failed**  | Connection error (click to view details) |
| **Loading** | Server initializing                      |

**Refreshing Tools:**
Click the refresh button to rediscover available tools from a server after configuration changes or connection issues.

***

## MCP Configuration [#mcp-configuration]

### Basic Setup [#basic-setup]

**Location:** `.mcp.json` in project root or `~/.verdent/mcp.json` (global)

<CodeGroup>
  ```json PostgreSQL Server
  {
    "mcpServers": {
      "postgres": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://localhost:5432/myapp_dev"
        ]
      }
    }
  }
  ```

  ```json GitHub Server
  {
    "mcpServers": {
      "github": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-github"
        ],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
  ```

  ```json Multiple Servers
  {
    "mcpServers": {
      "postgres": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://localhost:5432/myapp_dev"
        ]
      },
      "github": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-github"
        ],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
  ```
</CodeGroup>

**Configuration Keys:**

* `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

<Tip>
  **Learn More About MCP:**

  * [Model Context Protocol Specification](https://modelcontextprotocol.io/specification)
  * [MCP Server Registry](https://mcp.so/servers) - Browse available MCP servers
  * [Official MCP Servers](https://github.com/modelcontextprotocol) - PostgreSQL, GitHub, Filesystem, and more
</Tip>

***

## MCP Plugins and Extensions [#mcp-plugins-and-extensions]

### Available Plugins [#available-plugins]

MCP plugins provide pre-built integrations for common tools and services. Browse the community registry at [mcp.so/servers](https://mcp.so/servers) or the [official MCP servers repo](https://github.com/modelcontextprotocol) for current availability.

**Common Plugin Categories:**

* **Database Integrations:** PostgreSQL, MySQL, MongoDB query tools
* **Cloud Services:** AWS, Azure, GCP API interactions
* **Developer Tools:** GitHub, GitLab, Jira, Linear integrations
* **CI/CD Platforms:** Jenkins, GitHub Actions, CircleCI
* **Monitoring Services:** Datadog, New Relic, Sentry
* **Communication:** Slack, Discord, Microsoft Teams notifications

### Plugin Installation [#plugin-installation]

**Installation Methods:**
Plugins are installed and configured through the MCP Settings interface, typically requiring:

* Plugin identifier or source
* Configuration parameters
* Authentication credentials (if applicable)

**Dependency Management:**
MCP plugins may have dependencies on external services or libraries. Installation processes handle dependency resolution automatically when possible.

***

## Custom MCP Server Development [#custom-mcp-server-development]

### Creating Custom Servers [#creating-custom-servers]

Advanced users can create custom MCP servers to integrate proprietary tools or domain-specific systems.

**Development Approach:**
Custom MCP servers implement the MCP protocol specification, exposing tool capabilities that Verdent can invoke. Refer to the [Model Context Protocol specification](https://modelcontextprotocol.io/specification) for implementation details and SDKs.

**Use Cases for Custom Servers:**

* **Internal API Integration:** Connect to company-specific APIs and services
* **Legacy System Bridges:** Enable Verdent to interact with legacy infrastructure
* **Specialized Data Sources:** Access proprietary databases or data warehouses
* **Workflow Automation:** Trigger custom build, deployment, or testing pipelines

### Integration Patterns [#integration-patterns]

**Workspace-Level Configuration:**
MCP servers can be configured at workspace level for project-specific integrations, enabling teams to share MCP configurations through version control.

**Tool Interoperability:**
MCP-provided tools integrate seamlessly with Verdent's built-in tools (`file_read`, `bash`, `spawn_subagent`), enabling complex workflows combining multiple tool types.

***

## Desktop-Specific MCP Features [#desktop-specific-mcp-features]

### Per-Project Configuration [#per-project-configuration]

| Configuration Level | Location                    | Scope                   |
| ------------------- | --------------------------- | ----------------------- |
| **Global**          | `~/.verdent/mcp.json`       | All projects            |
| **Project**         | `.mcp.json` in project root | Single project          |
| **Worktree**        | Inherits from project       | Inherits project config |

### Multi-Worktree MCP [#multi-worktree-mcp]

MCP servers work across worktrees:

* **Shared Servers:** Base workspace MCP config shared by all worktrees
* **Isolated Operations:** Each worktree maintains separate MCP session state
* **Parallel Access:** Multiple worktrees can use same MCP servers concurrently

### Project Switching [#project-switching]

When switching projects:

* Current project's MCP servers are loaded
* Global MCP servers remain available
* Previous project's MCP connections are maintained in background

***

## MCP Workflow Examples [#mcp-workflow-examples]

### Database Query Integration [#database-query-integration]

**Scenario:** Query production database for debugging data issues.

**MCP Approach:**

```
User: "Check the orders table for customer ID 12345"
Verdent: [Uses MCP database server to execute safe read-only query]
        Results: 3 orders found for customer 12345
        [Displays formatted results]
```

The MCP database server handles authentication, query validation, and result formatting.

### Cloud Service Interaction [#cloud-service-interaction]

**Scenario:** Check AWS Lambda function logs for errors.

**MCP Approach:**

```
User: "Show me recent errors from the payment-processor Lambda function"
Verdent: [Invokes MCP AWS integration]
        [Retrieves CloudWatch logs for specified function]
        [Filters for ERROR level entries]
        [Presents formatted error summaries]
```

MCP AWS server manages authentication, API calls, and log parsing.

### CI/CD Pipeline Monitoring [#cicd-pipeline-monitoring]

**Scenario:** Check build status before deploying changes.

**MCP Approach:**

```
User: "Is the master branch build passing?"
Verdent: [Queries MCP CI/CD integration]
        Build #245: ✓ Passed (2 minutes ago)
        All tests passed, ready for deployment
```

MCP CI/CD server tracks pipeline status and provides real-time feedback.

***

## Security Considerations [#security-considerations]

### Authentication & Authorization [#authentication--authorization]

**Credential Management:**
MCP servers handle authentication to external services. Credentials are stored securely in MCP configuration and never exposed in chat history or code.

**Permission Scoping:**
Configure MCP servers with minimal necessary permissions. Use read-only access where possible, and restrict destructive operations.

### Safe Operations [#safe-operations]

**Command Review:**
Operations involving MCP tools appear in the conversation history, providing visibility and control.

**Audit Logging:**
MCP server operations appear in Verdent's chat history, creating an audit trail of external system interactions.

***

## Troubleshooting MCP Integration [#troubleshooting-mcp-integration]

### Common Issues [#common-issues]

**Connection Failures:**

* Verify network connectivity to MCP server
* Check authentication credentials in `mcp.json`
* Ensure MCP server is running and accessible
* Validate configuration file syntax

**Permission Errors:**

* Confirm API keys or credentials have required permissions
* Check service quotas or rate limits
* Verify firewall rules allow MCP traffic

**Tool Invocation Issues:**

* Ensure MCP server exposes expected tools correctly
* Check tool parameter formats match server expectations
* Review MCP server logs for error details

### Getting Help [#getting-help]

**Support Channels:**

* Verdent support: [support@verdent.ai](mailto:support@verdent.ai)
* [MCP protocol documentation](https://modelcontextprotocol.io)
* [Verdent Discord community](https://discord.com/invite/NGjXEZcbJq)

**Diagnostic Information:**
When reporting MCP issues, provide:

* MCP server type and version
* Configuration details (sanitized of credentials)
* Error messages from chat history
* MCP server logs (if accessible)

***

## FAQs [#faqs]

<AccordionGroup>
  <Accordion title="Do MCP servers use credits?">
    MCP server operations consume credits based on the model processing the results. The MCP server itself doesn't use credits directly.
  </Accordion>

  <Accordion title="Are MCP servers project-specific?">
    No. MCP servers are configured at the user level, not per project. All configured servers are available across all your projects.
  </Accordion>

  <Accordion title="Are my credentials safe in mcp.json?">
    Credentials in mcp.json are stored locally on your machine and never sent to Verdent servers. Use environment variables (`${VAR_NAME}`) for sensitive values.
  </Accordion>

  <Accordion title="Do MCP servers run continuously?">
    MCP servers start when needed and run during your session. They don't consume resources when Verdent is closed.
  </Accordion>

  <Accordion title="Can MCP servers modify my files?">
    MCP servers have the permissions you configure. Use read-only access where possible and restrict destructive operations.
  </Accordion>

  <Accordion title="How do I know if my MCP server is working?">
    Ask Verdent to use a tool from the MCP server. Successful responses indicate the connection is working. Check the Troubleshooting section if issues occur.
  </Accordion>
</AccordionGroup>