Setup MCP & ENV

Benchmarked against: Anthropic — Get API key Scope: MCP server configuration + environment variables for a new ship or agent

MCP (Model Context Protocol) is the communication standard between agents and tools. Every agent needs at least one MCP server configured to operate. This page covers the full setup for both Claude Code CLI and Claude Desktop App agents.

---

MCP server inventory

A fully configured SuperPortia ship runs these MCP servers:

Server	Type	Transport	Purpose
Cloud UB	Custom	Remote HTTP	Shared fleet knowledge, WO system, messaging
Local UBI	Custom	stdio (Python)	Local tools, dispatch engine, MTAAA pipeline
Cloudflare	Official	Remote	Cloudflare API operations (Workers, D1, R2)
Supabase	Official	Remote	Database operations for web projects
Chrome	Extension	WebSocket	Browser automation
Memory	Official	stdio	Personal knowledge graph
Filesystem	Official	stdio	Safe file operations outside repo
Obsidian	Community	stdio	Note search (legacy)

---

Configuration files

Claude Code CLI (~/.claude.json or project settings.json)

MCP servers for CLI agents are configured in Claude Code's settings:

{
  "mcpServers": {
    "cloud-ub": {
      "url": "https://your-cloud-ub-worker.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AUTH_TOKEN"
      }
    },
    "local-ubi": {
      "command": "python",
      "args": ["-m", "ub.mcp_server"],
      "cwd": "/path/to/superportia",
      "env": {
        "SP_SHIP_ID": "SS1",
        "SP_AGENT_ID": "Mac CLI 小克"
      }
    }
  }
}

Claude Desktop App (claude_desktop_config.json)

For App-based agents (Chat tab = 小西, Code tab = 小克):

{
  "mcpServers": {
    "cloud-ub": {
      "url": "https://your-cloud-ub-worker.workers.dev/mcp"
    },
    "local-ubi": {
      "command": "python",
      "args": ["-m", "ub.mcp_server"],
      "cwd": "/path/to/superportia"
    }
  }
}

---

Environment variables

Required for all agents

Variable	Value	Purpose
SP_SHIP_ID	SS1, SS2, or SS3	Ship identity for UB tagging
SP_AGENT_ID	Agent identity string	Agent identity for audit trail

Required for Local UBI

Variable	Value	Purpose
GROQ_API_KEY	Groq API key	Free engine access
GEMINI_API_KEY	Google AI API key	Gemini engine + embeddings
DEEPSEEK_API_KEY	DeepSeek API key	DeepSeek engine
MISTRAL_API_KEY	Mistral API key	Mistral engine
ZHIPU_API_KEY	Zhipu API key	GLM-5 engine

Required for Cloud UB

Variable	Value	Purpose
CLOUD_UB_URL	Worker URL	Cloud UB endpoint
CLOUD_UB_AUTH	Bearer token	Authentication

---

Verification checklist

After configuration, verify each MCP server:

Check	Command	Expected
Cloud UB health	cloud_ub_health()	{"status": "healthy"}
Agent registration	agent_heartbeat()	{"status": "registered"}
Mailbox access	check_agent_mailbox()	No error
UB search	search_brain("test")	Returns results array
Engine availability	list_models()	Shows configured providers
File tools	ubi_list_directory(path="/tmp")	Directory listing

---

Ship identity naming

Each agent has a unique identity based on ship + interface:

Ship	CLI Agent	App Agent
SS1	Mac CLI 小克	Mac App 小克
SS1	Mac CLI 小A	Mac App 小A
SS2	Win CLI 小克	Win App 小克
SS2	Win CLI 小A	Win App 小A
SS3	Web 小克	—

Set SP_AGENT_ID to the exact identity string. This appears in UB entries, WO audit trails, and agent messages.

---

Troubleshooting

Symptom	Likely cause	Fix
MCP server keeps restarting	Python environment issue	Check .venv activation, dependencies
agent_heartbeat() fails	Cloud UB unreachable	Check CLOUD_UB_URL, network, Worker status
Tools return empty	Wrong ship/agent ID	Verify SP_SHIP_ID and SP_AGENT_ID
list_models() shows missing keys	API keys not set	Add keys to .env or environment
Chrome MCP disconnected	Extension not running	Open Chrome, check extension status

---

Related pages

Page	Relationship
Quickstart	End-to-end first run
First Heartbeat	Agent registration details
MCP Servers Overview	All MCP servers
Fleet Management	Ship architecture