# MCP Plugins

Connect external tools to TeamDay agents — OAuth integrations, database connectors, SEO tools, and any MCP server via URL.

# MCP Plugins

MCP (Model Context Protocol) plugins connect external tools and services to your agents. This guide covers supported integrations, configuration patterns, and how MCPs work at different levels.

For basic MCP concepts, see [What Are MCP Servers?](https://docs.teamday.ai/guides/mcp-servers/what-are-mcp-servers). For installation, see [Installing MCP Servers](https://docs.teamday.ai/guides/mcp-servers/installing).

---

## Two Levels of MCP Attachment

MCPs can be attached at two levels, and when an agent chats in a space, it gets the **union** of both:

| Level | How | Available To |
|-------|-----|-------------|
| **Agent level** | Via `mcpInstanceIds` on the agent | Follows the agent everywhere — org chat, any space |
| **Space level** | Via `mcpRefs` on the space | Available to all agents chatting in that space |

When an agent chats in a space, it gets access to both its own MCPs and the space's MCPs. When an agent chats at the org level (no space), it only gets its own agent-level MCPs.

---

## Supported Integrations

### SEO

| Integration | What It Provides |
|-------------|-----------------|
| **Ahrefs** | Backlink analysis, keyword research, site audit, rank tracking |
| **Google Search Console** | Search impressions, clicks, CTR, keyword positions |
| **SE Ranking** | Keyword tracking, competitor analysis, site audit |

### Analytics

| Integration | What It Provides |
|-------------|-----------------|
| **Google Analytics** | GA4 traffic data, page metrics, user behavior |

### CMS

| Integration | What It Provides |
|-------------|-----------------|
| **WordPress** | Post management, content publishing (self-hosted and .com) |

### Database

| Integration | What It Provides |
|-------------|-----------------|
| **PostgreSQL** | Query and manage PostgreSQL databases |
| **MySQL** | Query and manage MySQL databases |
| **[BigQuery](https://docs.teamday.ai/guides/bigquery-agent-activation)** | Google BigQuery data warehouse queries |
| **Firestore** | Google Cloud Firestore document database |
| **Cloud SQL** | Google Cloud SQL managed databases |
| **SQLite** | Local SQLite database access |
| **MongoDB** | MongoDB document database queries |
| **ClickHouse** | ClickHouse analytics database |
| **Neo4j** | Neo4j graph database queries |
| **Snowflake** | Snowflake data warehouse queries |
| **Elasticsearch** | Elasticsearch search and analytics |
| **MSSQL** | Microsoft SQL Server queries |

### Advertising

| Integration | What It Provides |
|-------------|-----------------|
| **Meta Ads** | Facebook/Instagram ad campaign management and reporting |
| **Google Ads** | Google Ads campaign management and reporting |

### Communication

| Integration | What It Provides |
|-------------|-----------------|
| **Brevo** | Transactional and marketing email via Brevo API |

### Search

| Integration | What It Provides |
|-------------|-----------------|
| **Brave Search** | Web search via Brave Search API |
| **DataForSEO** | SERP data, keyword metrics, competitor analysis |
| **Exa** | Neural search for finding relevant content |

### Generic

| Integration | What It Provides |
|-------------|-----------------|
| **Any MCP via URL** | Connect any MCP server using `mcp-oauth` with auto-discovery |

---

## Transport Types

MCPs communicate using one of two transport protocols:

| Transport | Description | Use Case |
|-----------|-------------|----------|
| **stdio** | Local process execution | Most MCPs — runs as a child process in the sandbox |
| **streamable-http** | Remote HTTP-based connection | OAuth MCPs like Ahrefs, Google Search Console — connects to a remote server |

---

## OAuth MCP Integrations

Some MCP servers require OAuth authentication to access user data (e.g., Google Analytics, Google Search Console, Ahrefs).

### How OAuth MCPs Work

1. You install the MCP on a space or agent
2. The web app shows a **Connect** button
3. You authenticate with the external service via OAuth in the browser
4. Tokens are stored encrypted and refreshed automatically

### Token Lifecycle

- OAuth tokens are stored encrypted per-space
- Access tokens are refreshed automatically before expiration
- If a token expires or is revoked, the UI prompts you to reconnect

---

## MCP Configuration via API

### Create MCP Instance

```bash
curl -X POST "https://cc.teamday.ai/api/v1/mcps" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "custom-api",
    "type": "stdio",
    "command": "node",
    "args": ["dist/index.js"],
    "env": {
      "API_KEY": "your-api-key"
    }
  }'
```

### Update MCP Configuration

```bash
curl -X PATCH "https://cc.teamday.ai/api/v1/mcps/<id>" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "env": {
      "API_KEY": "new-api-key"
    }
  }'
```

### Attach MCP to an Agent

```bash
curl -X PATCH "https://cc.teamday.ai/api/v1/agents/<agent-id>" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"addMcpInstanceIds": ["mcp-id-1"]}'
```

### Attach MCP to a Space

```bash
curl -X PATCH "https://cc.teamday.ai/api/v1/spaces/<space-id>" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"addMcps": ["mcp-id-1"]}'
```

---

## Configuration Patterns

### Environment Variable References

In `.mcp.json`, reference Space secrets with `${VAR_NAME}`:

```json
{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-postgres", "${DATABASE_URL}"]
    },
    "api-tool": {
      "command": "node",
      "args": ["tools/api/index.js"],
      "env": {
        "API_KEY": "${API_KEY}",
        "API_SECRET": "${API_SECRET}"
      }
    }
  }
}
```

Store the actual values as secrets:

```bash
teamday spaces set-secret <space-id> \
  DATABASE_URL=postgres://user:pass@host/db \
  API_KEY=abc123 \
  API_SECRET=xyz789
```

### Multiple MCP Servers

A Space can have many MCP servers. Each runs as a separate process:

```json
{
  "mcpServers": {
    "google-analytics": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-google-analytics"],
      "env": {"GA_PROPERTY_ID": "${GA_PROPERTY_ID}"}
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-postgres", "${DATABASE_URL}"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-github"],
      "env": {"GITHUB_TOKEN": "${GITHUB_TOKEN}"}
    }
  }
}
```

### Disabling Tools

If an MCP provides tools you don't want agents to use, disable them at the Space level:

```bash
curl -X PATCH "https://cc.teamday.ai/api/v1/spaces/<space-id>" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"disabledTools": ["mcp__github__create_issue"]}'
```

---

## Programmatic vs File-Based

| Approach | How | Best For |
|----------|-----|---------|
| **API/CLI** | `teamday mcps create` | Org-wide MCP instances, managed centrally |
| **.mcp.json** | File in Space root | Per-Space configuration, version controlled |

Programmatic MCPs (via API) override file-based MCPs with the same name.

---

## Next Steps

- [MCP Servers](https://docs.teamday.ai/guides/mcp-servers/what-are-mcp-servers) — MCP concepts
- [Installing MCP Servers](https://docs.teamday.ai/guides/mcp-servers/installing) — Installation guide
- [Creating Custom MCP Servers](https://docs.teamday.ai/guides/mcp-servers/creating-custom) — Build your own
- [Tools Overview](https://docs.teamday.ai/guides/tools) — All tool categories