---
id: kb-016
title: System-Scoped MCP Setup - atoms-mcp-prod
scope:
  type: project
  id: 4sgm
purpose: alignment-mcp-scoping
tags:
  - mcp
  - orchestration
  - configuration
topics:
  - engineering
  - infrastructure
version: 1
created: 2025-11-26
updated: 2025-11-26
author: droid-agent
status: final
related_ids:
  - kb-012
  - kb-015
external_refs: []
---

# System-Scoped MCP Setup: atoms-mcp-prod

## Overview

`atoms-mcp-prod` is now automatically composed as a **system-scoped MCP server**. This architecture ensures that the official platform tools are observable, configurable, and available to all users by default without manual installation.

## Implementation Details

### 1. Database Registration
The server is registered in the `mcp_servers` table with:
- **`scope = 'system'`**: Enables global availability.
- **`is_internal = true`**: Identifies it as an official platform server.
- **`enabled = true`**: Active for all users by default.

### 2. Automatic Composition
The `compose_mcp_servers()` logic follows a specific priority:
1. Load system-scoped servers (e.g., `atoms-mcp-prod`).
2. Load user/organization/project-specific servers.
3. Append local sandbox and codebase tools.

### 3. Unified Authentication
System-scoped servers leverage the existing AuthKit JWT:
- The token is extracted from the request context.
- Automatically passed via `Authorization: Bearer <token>` to the MCP server.
- Ensures RLS context is maintained across service boundaries.

---

## Migration & Verification

### Database Update
```sql
UPDATE mcp_servers 
SET scope = 'system', is_internal = true 
WHERE namespace = 'atoms-mcp';
```

### Environment Variables
- `ATOMS_MCP_PROD_URL`: Defaults to production but can be overridden for local development (e.g., `http://localhost:8000/api/mcp`).

---

## Benefits
- ✅ **Observable**: Visible in the management UI with platform badges.
- ✅ **Configurable**: Admins can toggle availability or override URLs via the frontend.
- ✅ **Maintenance**: Eliminated tool duplication in the `agentapi` codebase.
