> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weavemcp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup an Agent

> Deploy WeaveMCP agents to various platforms

# Setup an Agent

Deploy WeaveMCP agents to production environments using various platforms and deployment methods.

## Deployment Options

Choose from multiple deployment platforms based on your infrastructure needs:

<CardGroup cols={2}>
  <Card title="Kubernetes" icon="dharmachakra" href="/setup-an-agent/kubernetes">
    Container orchestration platform for scalable deployments
  </Card>

  <Card title="Docker Compose" icon="docker" href="/setup-an-agent/docker-compose">
    Multi-container applications for development and testing
  </Card>

  <Card title="AWS EC2" icon="aws" href="/setup-an-agent/aws-ec2">
    Amazon cloud instances for reliable hosting
  </Card>

  <Card title="Google Cloud Run" icon="google-cloud" href="/setup-an-agent/google-cloud-run">
    Serverless containers with automatic scaling
  </Card>
</CardGroup>

## Why Deploy Agents?

While the WeaveMCP CLI (`weave`) works great for local development, deploying agents provides several benefits for production use:

### Self-Hosted MCP Servers

* **Security**: Keep sensitive data and processing within your infrastructure
* **Performance**: Reduce latency by running servers closer to your data sources
* **Compliance**: Meet regulatory requirements for data residency
* **Custom Logic**: Run proprietary or custom MCP server implementations

### Team Collaboration

* **Shared Resources**: Make MCP servers available to your entire organization
* **Centralized Management**: Configure and monitor all servers from one place
* **Access Control**: Fine-grained permissions for different team members
* **Usage Monitoring**: Track and optimize MCP server usage across your team

### Production Reliability

* **High Availability**: Automatic failover and redundancy
* **Scaling**: Handle increased load automatically
* **Monitoring**: Built-in observability and alerting
* **Backup & Recovery**: Automated backup strategies

## Architecture Overview

WeaveMCP agents act as bridges between your virtual MCP servers and actual MCP server implementations:

```
Claude Desktop  →  WeaveMCP Console  →  Virtual Server  →  Agent  →  MCP Server
    (Client)          (Control Plane)     (Endpoint)     (Bridge)   (Implementation)
```

### Components

1. **Virtual MCP Server**: A cloud-hosted endpoint that receives MCP requests
2. **Agent**: Self-hosted component that connects to virtual servers and manages local MCP servers
3. **MCP Servers**: Your actual tool implementations (filesystem, database, APIs, etc.)

### Communication Flow

1. Claude Desktop makes an MCP request through the WeaveMCP proxy
2. Request is routed to your virtual server endpoint
3. Virtual server forwards the request to your deployed agent
4. Agent executes the request on the appropriate MCP server
5. Response flows back through the same chain

## Getting Started

### Prerequisites

Before deploying an agent, ensure you have:

* **WeaveMCP Account**: Sign up at [console.weavemcp.com](https://console.weavemcp.com)
* **Virtual MCP Server**: Created through the web console
* **Agent Token**: Generated for your virtual server
* **Target Platform**: Access to one of the supported deployment platforms

### Basic Setup Steps

1. **Create Virtual Server**: Use the web console to create a new virtual MCP server
2. **Generate Agent Token**: Create an authentication token for your agent
3. **Choose Deployment Method**: Select from Kubernetes, Docker Compose, AWS EC2, or Google Cloud Run
4. **Configure Agent**: Set up environment variables and configuration files
5. **Deploy**: Follow platform-specific deployment instructions
6. **Test Connection**: Verify the agent connects to your virtual server

### Environment Configuration

All deployment methods require these essential environment variables:

```bash theme={null}
WEAVEMCP_AGENT_TOKEN=your-agent-token-here
WEAVEMCP_SERVER_URL=https://your-virtual-server.weavemcp.dev
WEAVEMCP_LOG_LEVEL=info
```

Optional configuration:

```bash theme={null}
WEAVEMCP_HEALTH_CHECK_PORT=8080
WEAVEMCP_METRICS_PORT=9090
WEAVEMCP_RETRY_ATTEMPTS=3
WEAVEMCP_RETRY_DELAY=5s
```

## Security Considerations

### Network Security

* **TLS Encryption**: All communication uses TLS 1.3
* **Token Authentication**: Agents authenticate using secure tokens
* **Network Isolation**: Deploy agents in private networks when possible
* **Firewall Rules**: Only allow outbound HTTPS connections to WeaveMCP

### Secrets Management

* **Token Storage**: Use platform-specific secret management (Kubernetes secrets, AWS Secrets Manager, etc.)
* **Environment Variables**: Avoid hardcoding tokens in configuration files
* **Rotation**: Regularly rotate agent tokens through the web console

### Access Control

* **Least Privilege**: Grant minimal required permissions to agent containers
* **Service Accounts**: Use dedicated service accounts with limited scopes
* **Network Policies**: Implement network policies to restrict agent communication

## Monitoring and Observability

### Health Checks

Agents expose health check endpoints:

```bash theme={null}
# Basic health check
curl http://localhost:8080/health

# Detailed status including MCP server connections
curl http://localhost:8080/status
```

### Metrics

Prometheus metrics are available at `/metrics`:

* `weavemcp_agent_requests_total`: Total MCP requests processed
* `weavemcp_agent_request_duration_seconds`: Request processing time
* `weavemcp_agent_connection_status`: Connection status to virtual server
* `weavemcp_mcp_server_status`: Status of individual MCP servers

### Logging

Agents log in JSON format with configurable levels:

```json theme={null}
{
  "timestamp": "2024-01-15T10:30:00Z",
  "level": "info",
  "message": "MCP request processed",
  "server": "filesystem-server",
  "method": "list_files",
  "duration_ms": 125
}
```

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Agent won't connect to virtual server">
    * Verify the `WEAVEMCP_SERVER_URL` is correct
    * Check the agent token is valid and not expired
    * Ensure outbound HTTPS (port 443) is allowed
    * Check agent logs for specific connection errors
  </Accordion>

  <Accordion title="MCP server not responding">
    * Verify MCP server is running and healthy
    * Check MCP server configuration in agent config
    * Review MCP server logs for errors
    * Test MCP server directly if possible
  </Accordion>

  <Accordion title="High latency or timeouts">
    * Check network connectivity between components
    * Review resource limits (CPU, memory) on agent
    * Monitor MCP server performance
    * Consider deploying agents closer to MCP servers
  </Accordion>

  <Accordion title="Authentication failures">
    * Regenerate agent token from web console
    * Verify token is correctly set in environment
    * Check token hasn't expired
    * Ensure virtual server is active
  </Accordion>
</AccordionGroup>

### Debug Mode

Enable debug logging for detailed troubleshooting:

```bash theme={null}
WEAVEMCP_LOG_LEVEL=debug
```

This provides:

* Detailed request/response logging
* Connection status information
* MCP server communication details
* Performance metrics

## Next Steps

Choose your deployment platform to get started:

<CardGroup cols={2}>
  <Card title="Start with Docker Compose" icon="docker" href="/setup-an-agent/docker-compose">
    Quickest way to test agent deployment locally
  </Card>

  <Card title="Production with Kubernetes" icon="dharmachakra" href="/setup-an-agent/kubernetes">
    Scalable production deployment
  </Card>

  <Card title="Cloud with AWS EC2" icon="aws" href="/setup-an-agent/aws-ec2">
    Simple cloud deployment
  </Card>

  <Card title="Serverless with Cloud Run" icon="google-cloud" href="/setup-an-agent/google-cloud-run">
    Automatic scaling and managed infrastructure
  </Card>
</CardGroup>

## Advanced Topics

Once you have basic agent deployment working:

* **Load Balancing**: Deploy multiple agents for high availability
* **Auto Scaling**: Scale agents based on demand
* **Multi-Region**: Deploy agents across multiple regions
* **Custom MCP Servers**: Integrate your own MCP server implementations
* **CI/CD Integration**: Automate agent deployment and updates