diff --git a/mcp-gateway/forgejo-mcp/INTEGRATION_GUIDE.md b/mcp-gateway/forgejo-mcp/INTEGRATION_GUIDE.md
new file mode 100644
index 0000000..edca352
--- /dev/null
+++ b/mcp-gateway/forgejo-mcp/INTEGRATION_GUIDE.md
@@ -0,0 +1,438 @@
+# Forgejo-MCP Gateway Integration Guide
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   MCP Gateway (Port 4444)               │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │  OAuth 2.1 + Tool Registry + Request Router     │   │
+│  └────────┬────────────────────────────────────────┘   │
+└───────────┼─────────────────────────────────────────────┘
+            │
+            │ MCP_BACKEND_FORGEJO=http://mcp-forgejo:8400/mcp
+            │
+┌───────────▼─────────────────────────────────────────────┐
+│            Forgejo-MCP Service (Port 8400)              │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │  12 Repository/Issue/PR/File Tools              │   │
+│  │  Async HTTP Client for Forgejo API             │   │
+│  └────────┬────────────────────────────────────────┘   │
+└───────────┼─────────────────────────────────────────────┘
+            │ FORGEJO_ACCESS_TOKEN
+            │
+┌───────────▼─────────────────────────────────────────────┐
+│   Forgejo Instance (http://10.0.0.25:34577)            │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │  Repositories, Issues, PRs, Users               │   │
+│  └─────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Integration Points
+
+### 1. Docker Network
+
+The `forgejo-mcp` service joins the `mcpnet` network, allowing internal communication with the gateway:
+
+```yaml
+networks:
+  mcpnet:
+    driver: bridge
+
+services:
+  forgejo-mcp:
+    networks: [mcpnet]
+```
+
+### 2. Gateway Backend Registration
+
+In `gateway_proxy.py`, backends are discovered via environment variables:
+
+```python
+def load_backends() -> dict[str, str]:
+    backends = {}
+    for key, value in os.environ.items():
+        if key.startswith("MCP_BACKEND_"):
+            name = key[len("MCP_BACKEND_"):].lower()
+            backends[name] = value
+    return backends
+```
+
+The `docker-compose.yml` provides:
+```
+MCP_BACKEND_FORGEJO=http://mcp-forgejo:8400/mcp
+```
+
+This automatically registers the Forgejo-MCP service with the gateway.
+
+### 3. Tool Discovery
+
+When Claude requests tools, the gateway:
+
+1. Makes a `GET /tools` request to `http://mcp-forgejo:8400/mcp`
+2. Receives the list of 12 available tools
+3. Registers them with the tool registry
+4. Prefixes tools with the backend name: `forgejo_list_repositories`, etc.
+
+### 4. Request Routing
+
+When Claude calls a `forgejo_*` tool:
+
+1. Gateway receives the request with tool name and arguments
+2. Routes to the appropriate backend (Forgejo-MCP)
+3. Makes `POST /call_tool` request to Forgejo-MCP
+4. Returns results to Claude
+
+## Configuration Checklist
+
+Before deploying, verify:
+
+### Environment Variables
+- [ ] `FORGEJO_URL` is set (default: `http://10.0.0.25:34577`)
+- [ ] `FORGEJO_ACCESS_TOKEN` is set to your token
+- [ ] Token has `repo` scope
+
+### Docker Compose
+- [ ] `docker-compose.yml` includes `forgejo-mcp` service
+- [ ] Service port is `8400`
+- [ ] Environment variables are passed to container
+- [ ] `networks: [mcpnet]` is configured
+- [ ] Health check is configured
+
+### Gateway Configuration
+- [ ] `docker-compose.yml` gateway includes `MCP_BACKEND_FORGEJO` environment
+- [ ] Gateway depends on `forgejo-mcp` service
+
+## Health Checks
+
+### Service Health
+
+```bash
+# Check service is running
+docker-compose ps forgejo-mcp
+
+# Check logs
+docker-compose logs forgejo-mcp
+
+# Manual health check
+curl http://localhost:8400/health
+```
+
+### Network Connectivity
+
+```bash
+# From gateway container, ping forgejo-mcp
+docker exec mcp-gateway ping mcp-forgejo
+
+# From gateway container, check tool endpoint
+docker exec mcp-gateway curl http://mcp-forgejo:8400/tools
+```
+
+### Gateway Integration
+
+```bash
+# Check gateway logs for backend initialization
+docker-compose logs gateway | grep -i forgejo
+
+# Should show:
+# Backend configured: forgejo -> http://mcp-forgejo:8400/mcp
+```
+
+## Deployment Steps
+
+### 1. Prepare Environment
+
+```bash
+cd /path/to/mcp-gateway
+
+# Add to .env file
+echo "FORGEJO_URL=http://10.0.0.25:34577" >> .env
+echo "FORGEJO_ACCESS_TOKEN=df0555d179c7ce6d11c6605b7ddad0921c3c4c83" >> .env
+```
+
+### 2. Build Service
+
+```bash
+# Build the Forgejo-MCP image
+docker-compose build forgejo-mcp
+
+# Output should show:
+# Step 1/6 : FROM python:3.11-slim
+# ...
+# Successfully built <image_id>
+```
+
+### 3. Start Service
+
+```bash
+# Start the Forgejo-MCP service
+docker-compose up -d forgejo-mcp
+
+# Wait for startup (healthcheck)
+sleep 5
+
+# Verify running
+docker-compose ps forgejo-mcp
+# Should show "Up" status
+```
+
+### 4. Restart Gateway
+
+If the gateway was already running, restart it to pick up the new backend:
+
+```bash
+docker-compose restart gateway
+
+# Check logs
+docker-compose logs -f gateway
+```
+
+### 5. Verify Tools
+
+Test tool discovery through the gateway:
+
+```bash
+# List available tools (if gateway provides this endpoint)
+curl -H "Authorization: Bearer YOUR_GATEWAY_TOKEN" \
+  http://localhost:4444/tools | jq '.[] | select(.name | startswith("forgejo"))'
+
+# Should list all 12 forgejo_* tools
+```
+
+## Tool Availability
+
+Once integrated, these tools will be available:
+
+**Repository Management** (3 tools)
+- `forgejo_list_repositories`
+- `forgejo_get_repository`
+- `forgejo_create_repository`
+
+**Issue Management** (3 tools)
+- `forgejo_list_issues`
+- `forgejo_create_issue`
+- `forgejo_update_issue`
+
+**Pull Requests** (2 tools)
+- `forgejo_list_pull_requests`
+- `forgejo_create_pull_request`
+
+**Branches & Files** (2 tools)
+- `forgejo_list_branches`
+- `forgejo_get_file`
+
+**Search & Users** (2 tools)
+- `forgejo_search_repositories`
+- `forgejo_get_user`
+
+## Testing Integration
+
+### Test 1: List Repositories
+
+Request to gateway:
+```json
+{
+  "tool": "forgejo_list_repositories",
+  "arguments": {
+    "owner": "your-username"
+  }
+}
+```
+
+Expected: List of repositories for the user
+
+### Test 2: Get Repository Details
+
+Request to gateway:
+```json
+{
+  "tool": "forgejo_get_repository",
+  "arguments": {
+    "owner": "your-username",
+    "repo": "your-repo"
+  }
+}
+```
+
+Expected: Detailed repository information
+
+### Test 3: List Issues
+
+Request to gateway:
+```json
+{
+  "tool": "forgejo_list_issues",
+  "arguments": {
+    "owner": "your-username",
+    "repo": "your-repo",
+    "state": "open"
+  }
+}
+```
+
+Expected: Open issues for the repository
+
+## Troubleshooting Integration
+
+### Issue: Service doesn't start
+
+```bash
+# Check logs
+docker-compose logs forgejo-mcp
+
+# Common causes:
+# - Missing environment variables
+# - Port 8400 already in use
+# - Invalid base image
+```
+
+### Issue: Gateway can't connect
+
+```bash
+# Check network
+docker network inspect mcpnet
+
+# Check service IP
+docker inspect mcp-forgejo | grep IPAddress
+
+# Test from gateway container
+docker exec mcp-gateway curl -v http://mcp-forgejo:8400/health
+```
+
+### Issue: Tools not appearing in gateway
+
+```bash
+# Check gateway backend configuration
+docker-compose logs gateway | grep -i backend
+
+# Check gateway can reach service
+docker exec mcp-gateway curl http://mcp-forgejo:8400/tools
+
+# Restart gateway
+docker-compose restart gateway
+```
+
+### Issue: Authentication fails
+
+```bash
+# Test token directly
+curl -H "Authorization: token df0555d179c7ce6d11c6605b7ddad0921c3c4c83" \
+  http://10.0.0.25:34577/api/v1/user
+
+# Should return user info, not 401
+```
+
+## Performance Considerations
+
+### Request Latency
+
+- Gateway to Forgejo-MCP: ~5-10ms (local network)
+- Forgejo-MCP to Forgejo: ~10-50ms (HTTP API)
+- Total: ~15-60ms per tool call
+
+### Concurrent Requests
+
+The Forgejo-MCP server uses async Python with httpx, supporting:
+- Multiple concurrent requests
+- Connection pooling
+- Efficient I/O handling
+
+### Rate Limiting
+
+Forgejo local instances typically have no rate limiting. For remote instances, be aware of:
+- API rate limits (if enforced)
+- Token usage monitoring
+- Large result set pagination
+
+## Security Integration
+
+### Token Management
+
+The token is:
+- Passed via environment variable (not hardcoded)
+- Used in HTTP header: `Authorization: token <token>`
+- Should be rotated periodically
+
+### Network Security
+
+- Internal network (`mcpnet`) - secure local communication
+- External access only through gateway (port 4444)
+- Gateway handles authentication (OAuth 2.1)
+
+### Data Flow
+
+```
+Claude Client
+    ↓
+    └─→ Gateway (authenticated)
+        ├─ Validates request
+        ├─ Routes to Forgejo-MCP
+        └─ Returns response
+            └─→ Forgejo-MCP
+                ├─ Uses token from env
+                └─ Calls Forgejo API
+                    └─→ Forgejo Instance
+```
+
+## Monitoring
+
+### Log Aggregation
+
+```bash
+# View all service logs
+docker-compose logs -f
+
+# View specific service
+docker-compose logs -f forgejo-mcp
+
+# Follow errors only
+docker-compose logs -f 2>&1 | grep ERROR
+```
+
+### Health Monitoring
+
+```bash
+# Set up monitoring
+watch -n 5 'docker-compose ps'
+
+# Check service health periodically
+*/5 * * * * docker-compose exec mcp-forgejo curl -f http://localhost:8400/health
+```
+
+## Updating the Service
+
+To update the Forgejo-MCP code:
+
+```bash
+# Edit forgejo_mcp.py
+
+# Rebuild
+docker-compose build --no-cache forgejo-mcp
+
+# Restart
+docker-compose up -d forgejo-mcp
+
+# Check logs
+docker-compose logs -f forgejo-mcp
+```
+
+## Integration with Claude.ai
+
+Once deployed:
+
+1. Connect your MCP gateway to Claude.ai
+2. The gateway exposes `forgejo_*` tools
+3. Claude can use these tools to:
+   - List and explore repositories
+   - Create and manage issues
+   - Work with pull requests
+   - Read repository files
+   - Search repositories
+
+Example Claude prompt:
+> List all open issues in my main project and create a summary
+
+This would use:
+- `forgejo_list_issues` - Get open issues
+- Process and summarize results