# Installing MCP Servers

How to install and configure MCP server integrations on TeamDay Spaces — via UI, CLI, API, or configuration files.

# Installing MCP Servers

MCP servers are installed per-Space. Once installed, all agents in that Space can use the MCP's tools.

---

## Installation Methods

### Via Web App

1. Open your Space
2. Go to **Space Settings**
3. Navigate to the **Integrations** or **MCPs** tab
4. Browse available MCPs or add a custom one
5. Configure credentials if required
6. Save

### Via CLI

First, create an MCP instance for your organization:

```bash
teamday mcps create \
  --type google-search \
  --name "Google Search" \
  --description "Web search integration"
```

Then add it to a Space:

```bash
teamday spaces add-mcp <space-id> <mcp-id>
```

### Via API

Create an 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": "google-analytics",
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-google-analytics"],
    "env": {
      "GA_PROPERTY_ID": "12345678"
    }
  }'
```

Add 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>"]}'
```

### Via .mcp.json (File-Based)

Place an `.mcp.json` file in the Space root:

```json
{
  "mcpServers": {
    "google-analytics": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-google-analytics"],
      "env": {
        "GA_PROPERTY_ID": "${GA_PROPERTY_ID}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-filesystem", "/data/reports"]
    }
  }
}
```

Environment variable references (`${VAR}`) are resolved from the Space's secrets at runtime.

### Via TeamdayAdmin (In-Chat)

An agent can install MCPs programmatically:

```json
{
  "action": "createMcp",
  "data": {
    "name": "google-analytics",
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-google-analytics"],
    "env": {
      "GA_PROPERTY_ID": "12345678"
    }
  }
}
```

Browse available MCPs:

```json
{
  "action": "browseMcpRegistry"
}
```

---

## Configuration

### Environment Variables

MCP servers often need API keys or configuration values. Store these as Space secrets:

```bash
teamday spaces set-secret <space-id> GA_PROPERTY_ID=12345678 AHREFS_API_KEY=abc123
```

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

```json
{
  "mcpServers": {
    "my-tool": {
      "command": "node",
      "args": ["tool.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}
```

### OAuth MCPs

Some integrations use OAuth for authentication (e.g., Google Analytics, Google Search Console):

1. Install the MCP on your Space
2. The UI prompts you to **Connect** via OAuth
3. You authenticate with the external service
4. Tokens are stored securely and refreshed automatically

If an OAuth token expires during a conversation, the agent can request re-authentication using the UICommand tool:

```json
{
  "action": "requestReauth",
  "target": "google-analytics"
}
```

### Credentials with MCP Instances

When creating MCP instances via the CLI, pass credentials as JSON:

```bash
teamday mcps create \
  --type slack \
  --name "Slack Bot" \
  --credentials '{"SLACK_TOKEN": {"value": "xoxb-...", "isSecret": true}}'
```

The `isSecret: true` flag ensures the value is encrypted at rest.

---

## Managing MCPs

### List MCPs

```bash
teamday mcps list
```

### View MCP Details

```bash
teamday mcps get <mcp-id>
```

### Remove from Space

```bash
teamday spaces remove-mcp <space-id> <mcp-id>
```

---

## Common MCP Configurations

### Google Analytics

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

Required secret: `GA_PROPERTY_ID`

### PostgreSQL

```json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-postgres", "${DATABASE_URL}"]
    }
  }
}
```

Required secret: `DATABASE_URL`

### GitHub

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

Required secret: `GITHUB_TOKEN`

---

## Troubleshooting

### MCP Not Starting

- Verify the command is installed: `npx -y <package-name> --help`
- Check that required environment variables are set as Space secrets
- Look at agent execution logs for startup errors

### Tools Not Appearing

- MCP servers load at conversation start — new MCPs won't appear in an ongoing chat
- Start a new conversation to pick up newly installed MCPs
- Verify the MCP is added to the Space (check Space details)

### Authentication Errors

- For OAuth MCPs: reconnect via Space settings
- For API key MCPs: verify the secret value is correct
- Check that secret names match what the MCP expects (case-sensitive)

---

## Next Steps

- [What Are MCP Servers?](https://docs.teamday.ai/guides/mcp-servers/what-are-mcp-servers) — Concepts and architecture
- [Creating Custom MCP Servers](https://docs.teamday.ai/guides/mcp-servers/creating-custom) — Build your own
- [Skills](https://docs.teamday.ai/guides/skills) — Alternative for local workflows