MCPs

AI can’t debug production if it can’t see production. MCP (Model Context Protocol) servers give your AI agent direct access to databases, monitoring, secrets, and testing tools.

What are MCPs?

MCPs are lightweight servers that expose specific capabilities to AI agents through a standardized protocol. They act as bridges between your AI editor and your infrastructure.

Available MCP Servers

Repo Hub’s MCP servers are maintained at arvore-mcp-servers.

Common MCPs (Practical Examples)

Repo Hub is OSS and doesn’t assume you have any specific MCP configured. Pick the MCPs that match your stack and the kind of work you want agents to do.

If you need multiple database connections, you can declare the same MCP server multiple times with different name values and different env/config (e.g. postgresql-identity, postgresql-billing).

Configuration

YAML

Declare MCPs in your hub.yaml:

mcps:
  # npm package — runs via npx
  - name: postgresql
    package: "@arvoretech/postgresql-mcp"
    env:
      PG_HOST: localhost
      PG_PORT: "5432"
      PG_DATABASE: myapp

  # npm package — no extra config needed
  - name: datadog
    package: "@arvoretech/datadog-mcp"

  # npm package
  - name: playwright
    package: "@playwright/mcp"

  # SSE URL — connects to a running server
  - name: linear
    url: "https://mcp.linear.app/sse"

  # Docker image — runs in a container
  - name: custom-tool
    image: "company/custom-mcp:latest"
    env:
      API_KEY: "${env:CUSTOM_TOOL_API_KEY}"

TypeScript

With hub.config.ts, use the type-safe MCP helpers:

import { defineConfig, mcp } from "@arvoretech/hub/config";

export default defineConfig({
  mcps: [
    mcp.postgresql("main-db", { env: { PG_HOST: "localhost", PG_DATABASE: "myapp" } }),
    mcp.datadog(),
    mcp.playwright(),
    mcp.memory(),
    mcp.launchdarkly(),
    mcp.custom("linear", { url: "https://mcp.linear.app/sse" }),
  ],
});

Each helper pre-fills the correct package name. See Configuration for the full list of MCP helpers.

*One of package, url, or image is required.

When you run hub generate, these are written to .cursor/mcp.json (Cursor), .mcp.json (Claude Code), .kiro/settings/mcp.json (Kiro), or opencode.json (OpenCode), making them available to all agents.

How Agents Use MCPs

Agents interact with MCPs through tool calls. For example:

• Database MCP: Agent queries the schema to understand table relationships before writing migrations
• Datadog MCP: Debugger agent searches logs and traces to identify the root cause of a production error
• Playwright MCP: QA agent navigates the web app, fills forms, and takes screenshots to verify UI changes
• npm Registry MCP: Coding agent checks package download counts and security signals before adding dependencies

Secret Environment Variables

Many MCPs need API keys, tokens, or credentials. Never hardcode secrets in hub.yaml — use the ${env:VAR_NAME} syntax to reference environment variables from your machine:

mcps:
  - name: datadog
    package: "@arvoretech/datadog-mcp"
    env:
      DATADOG_API_KEY: "${env:DATADOG_API_KEY}"
      DATADOG_APP_KEY: "${env:DATADOG_APP_KEY}"
      DATADOG_SITE: "${env:DATADOG_SITE}"

  - name: linear
    url: "https://mcp.linear.app/sse"
    env:
      LINEAR_API_KEY: "${env:LINEAR_API_KEY}"

  - name: postgresql
    package: "@arvoretech/postgresql-mcp"
    env:
      PG_HOST: localhost
      PG_PORT: "5432"
      PG_DATABASE: myapp
      PG_PASSWORD: "${env:PG_PASSWORD}"

When hub generate runs, ${env:VAR_NAME} is written as-is to the generated MCP config file. The editor (Cursor, Claude Code, Kiro, or OpenCode) resolves the reference at runtime, reading the value from your local environment.

This means:

• hub.yaml can be safely committed to git — no secrets in the repo
• Each developer sets their own keys in their shell profile (.zshrc, .bashrc, etc.) or a .env file
• The same config works across the team without sharing credentials

Setting up your environment

Add the variables to your shell profile:

export DATADOG_API_KEY="your-actual-key"
export DATADOG_APP_KEY="your-actual-key"
export LINEAR_API_KEY="lin_api_..."

Or use a tool like direnv with a .envrc file (added to .gitignore).

When to use plain values vs ${env:}

Security

• Database MCPs are read-only — Agents can query but cannot modify data
• Secrets are resolved at runtime — No credentials stored in generated files (use ${env:VAR})
• MCPs run locally — They connect to your infrastructure from your machine

MCP Proxy

If you use @arvoretech/mcp-proxy, you can route multiple MCP servers through a single proxy process. This reduces the number of running processes and lets the proxy handle connection management.

Declare the proxy MCP with an upstreams list referencing other MCP names:

mcps:
  - name: postgresql
    package: "@arvoretech/postgresql-mcp"
    env:
      PG_HOST: localhost
      PG_DATABASE: myapp

  - name: mysql
    package: "@arvoretech/mysql-mcp"
    env:
      MYSQL_HOST: localhost

  - name: mcp-proxy
    package: "@arvoretech/mcp-proxy"
    upstreams: [postgresql, mysql]

When hub generate runs:

• MCPs listed in upstreams are skipped as standalone entries (they won’t appear individually in the generated mcp.json)
• The proxy entry receives a MCP_PROXY_UPSTREAMS environment variable containing the upstream configurations as JSON
• All environment variables from upstream MCPs are collected and passed to the proxy process

This means the AI editor sees a single mcp-proxy server that exposes all tools from the upstream MCPs.

Creating Custom MCPs

You can create custom MCP servers following the MCP specification. A basic MCP server exposes:

1. Tools — Functions the AI can call
2. Resources — Data the AI can read
3. Prompts — Templates for common tasks

Reference your custom MCP in hub.yaml:

mcps:
  - name: my-custom-mcp
    package: "@company/my-mcp"
    env:
      API_URL: "https://api.internal.company.com"
      API_KEY: "${env:MY_CUSTOM_MCP_API_KEY}"