# Agent Gateway Registration
This document explains how to register the Twenty CRM MCP Server with an Agent Gateway for service discovery and orchestration.
## Overview
The Twenty CRM MCP Server can automatically register itself with an Agent Gateway, enabling:
- **Service Discovery**: Agents can discover and connect to the MCP server
- **Health Monitoring**: Gateway tracks server health and availability
- **Load Balancing**: Gateway can distribute requests across multiple instances
- **Centralized Management**: Single point of configuration for all MCP servers
## How It Works
The server implements automatic registration similar to how `ag-ui-server-agent` registers with the gateway:
1. **On Startup**: Server registers itself with the gateway
2. **Periodic Heartbeats**: Sends heartbeat every 60 seconds (configurable)
3. **On Shutdown**: Unregisters itself gracefully
4. **Auto-Recovery**: Automatically re-registers if heartbeat fails
## Configuration
### Environment Variables
Configure gateway registration by adding these to your `.env` file:
```bash
# Agent Gateway Configuration (Optional)
AGENT_GATEWAY_URL=http://localhost:8080
AGENT_GATEWAY_API_KEY=your_gateway_api_key
AGENT_NAME=twenty-crm-mcp-server
AGENT_VERSION=1.0.0
AGENT_DESCRIPTION=Twenty CRM MCP Server with GraphQL and REST API support
MCP_ENDPOINT=http://localhost:5008/mcp
HEALTH_ENDPOINT=http://localhost:5008/health
AGENT_REGISTRATION_INTERVAL=60000
```
### Configuration Options
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `AGENT_GATEWAY_URL` | No | - | URL of the Agent Gateway |
| `AGENT_GATEWAY_API_KEY` | No | - | API key for gateway authentication |
| `AGENT_NAME` | No | `twenty-crm-mcp-server` | Name of the agent |
| `AGENT_VERSION` | No | `1.0.0` | Version of the agent |
| `AGENT_DESCRIPTION` | No | Auto-generated | Description of the agent |
| `MCP_ENDPOINT` | No | `http://localhost:5008/mcp` | MCP protocol endpoint |
| `HEALTH_ENDPOINT` | No | `http://localhost:5008/health` | Health check endpoint |
| `AGENT_REGISTRATION_INTERVAL` | No | `60000` | Heartbeat interval in milliseconds |
## Registration Payload
The server registers with the following information:
```json
{
"name": "twenty-crm-mcp-server",
"type": "mcp",
"version": "1.0.0",
"description": "Twenty CRM MCP Server with GraphQL and REST API support",
"endpoint": "http://localhost:5008/mcp",
"healthCheckEndpoint": "http://localhost:5008/health",
"capabilities": [
"person.create",
"person.read",
"person.update",
"person.delete",
"person.list",
"company.create",
"company.read",
"company.list",
"opportunity.create",
"opportunity.read",
"opportunity.list"
],
"metadata": {
"framework": "typescript",
"protocol": "mcp",
"apis": ["graphql", "rest"],
"entities": ["person", "company", "opportunity"],
"registeredAt": "2025-12-29T12:00:00.000Z"
}
}
```
## Gateway API Endpoints
The server expects the gateway to expose these endpoints:
### Register Agent
```
POST /api/v1/agents/register
Content-Type: application/json
Authorization: Bearer <api_key>
Body: <registration payload>
```
### Heartbeat
```
POST /api/v1/agents/{agentName}/heartbeat
Content-Type: application/json
Authorization: Bearer <api_key>
Body: {
"timestamp": "2025-12-29T12:00:00.000Z",
"status": "healthy"
}
```
### Unregister Agent
```
DELETE /api/v1/agents/{agentName}
Authorization: Bearer <api_key>
```
## Usage Examples
### With Gateway (Automatic Registration)
```bash
# Add gateway URL to .env
echo "AGENT_GATEWAY_URL=http://localhost:8080" >> .env
# Start server - it will automatically register
npm start
```
Output:
```
🚀 MCP Streamable HTTP Server listening on port 5008
📖 Home Page: http://localhost:5008/
🔌 MCP Endpoint: http://localhost:5008/mcp
❤️ Health Check: http://localhost:5008/health
🌐 Agent Gateway: http://localhost:8080
Status: ✅ Registered
Agent: twenty-crm-mcp-server
```
### Without Gateway (Standalone)
```bash
# Don't set AGENT_GATEWAY_URL
npm start
```
Output:
```
🚀 MCP Streamable HTTP Server listening on port 5008
📖 Home Page: http://localhost:5008/
🔌 MCP Endpoint: http://localhost:5008/mcp
❤️ Health Check: http://localhost:5008/health
🌐 Agent Gateway: Not configured
```
## Docker Deployment with Gateway
### Docker Compose Example
```yaml
version: '3.8'
services:
twenty-mcp-server:
image: twenty-crm-mcp-server:latest
ports:
- "5008:8080"
environment:
- TWENTY_API_URL=https://api.twenty.com
- TWENTY_API_KEY=${TWENTY_API_KEY}
- AGENT_GATEWAY_URL=http://agent-gateway:8080
- AGENT_GATEWAY_API_KEY=${GATEWAY_API_KEY}
- MCP_ENDPOINT=http://twenty-mcp-server:8080/mcp
- HEALTH_ENDPOINT=http://twenty-mcp-server:8080/health
depends_on:
- agent-gateway
agent-gateway:
image: agent-gateway:latest
ports:
- "8080:8080"
```
### Kubernetes with Gateway
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: twenty-mcp-config
data:
AGENT_GATEWAY_URL: "http://agent-gateway-service:8080"
MCP_ENDPOINT: "http://twenty-crm-mcp-server-service:80/mcp"
HEALTH_ENDPOINT: "http://twenty-crm-mcp-server-service:80/health"
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: twenty-crm-mcp-server
spec:
template:
spec:
containers:
- name: mcp-server
image: twenty-crm-mcp-server:latest
env:
- name: AGENT_GATEWAY_URL
valueFrom:
configMapKeyRef:
name: twenty-mcp-config
key: AGENT_GATEWAY_URL
- name: AGENT_GATEWAY_API_KEY
valueFrom:
secretKeyRef:
name: gateway-secrets
key: api-key
```
## Monitoring
### Check Registration Status
The server logs gateway registration events:
```
[INFO] Creating Agent Gateway client {gateway: "http://localhost:8080", agent: "twenty-crm-mcp-server"}
[INFO] Registering with Agent Gateway {gateway: "http://localhost:8080", agent: "twenty-crm-mcp-server"}
[INFO] Successfully registered with Agent Gateway
[INFO] Agent Gateway registration started
```
### Health Check
Query the health endpoint to see gateway status:
```bash
curl http://localhost:5008/health
```
### Logs
Monitor gateway heartbeats:
```bash
# View logs
make docker-logs
# Or for Kubernetes
make k8s-logs
```
## Troubleshooting
### Gateway Not Responding
If registration fails:
1. Check gateway URL is correct
2. Verify gateway is running: `curl http://localhost:8080/health`
3. Check network connectivity
4. Verify API key if required
Logs will show:
```
[ERROR] Failed to register with Agent Gateway
```
The server will continue to retry every 60 seconds.
### Registration Timeout
If heartbeats fail, the server automatically re-registers on the next interval.
### Gateway Unavailable
The server continues to function normally even if the gateway is unavailable. Registration is optional and doesn't affect MCP functionality.
## Implementation Details
### Architecture
```
src/infrastructure/gateway/
└── agent-gateway-client.ts # Gateway registration client
```
The `AgentGatewayClient` class handles:
- Initial registration
- Periodic heartbeats
- Graceful unregistration
- Error handling and retries
### Integration
The gateway client is integrated into `MCPServer`:
- Created during initialization
- Started automatically if configured
- Stopped during cleanup
### Graceful Shutdown
On `SIGTERM` or `SIGINT`:
1. Server stops accepting new connections
2. Gateway client unregisters the agent
3. MCP server performs cleanup
4. Process exits
## Security
### API Key Management
- Store gateway API keys in environment variables
- Use Kubernetes secrets for production
- Never commit keys to version control
- Rotate keys regularly
### Network Security
- Use HTTPS for gateway communication
- Configure firewall rules
- Use service mesh for internal communication
- Enable mutual TLS if supported
## Best Practices
1. **Always set AGENT_NAME uniquely** for each instance
2. **Use internal service URLs** in Kubernetes/Docker
3. **Monitor registration logs** for failures
4. **Set reasonable heartbeat intervals** (60s recommended)
5. **Test failover scenarios** before production
6. **Use health checks** to verify registration
## Related Documentation
- [README.md](README.md) - Main project documentation
- [QUICKSTART.md](QUICKSTART.md) - Getting started guide
- [k8s/deployment.yaml](k8s/deployment.yaml) - Kubernetes deployment example
## Support
For issues with agent gateway registration:
1. Check logs: `make docker-logs` or `make k8s-logs`
2. Verify configuration: `make info`
3. Test health endpoint: `curl http://localhost:5008/health`
4. Review this documentation
