Open Horizons MCP Server

Model Context Protocol (MCP) server for Open Horizons - enables AI agents to read and write strategic alignment context.

What is This?

Open Horizons MCP Server connects AI coding assistants (like Claude Code) to your strategic alignment framework. Instead of making isolated technical decisions, AI agents can:

• Read your strategic context: Query missions, aims, initiatives, and tasks
• Log decisions back: Document why choices were made, tied to strategic goals
• Stay aligned: Every code change traces back to a mission

The result: AI that doesn't just code fast—it codes in alignment with your strategy.

Quick Start

1. Get Your API Key

1. Sign up at app.openhorizons.me
2. Go to Settings > API Keys
3. Create a new API key

2. Choose Your Setup Method

Option A: Plugin Setup (Recommended for Claude Code)

The plugin provides a guided /oh-mcp:setup command:

# Add the marketplace
claude plugin marketplace add cloud-atlas-ai/oh-mcp-server

# Install the plugin
claude plugin install oh-mcp@oh-mcp

# Restart Claude Code, then run:
/oh-mcp:setup

Option B: Direct CLI Setup (No Plugin Needed)

Use the claude mcp add command directly:

claude mcp add oh-mcp -s user \
  -e OH_API_URL=https://app.openhorizons.me \
  -e OH_API_KEY=your_api_key_here \
  -- npx -y @cloud-atlas-ai/oh-mcp-server

This adds the MCP server to ~/.claude.json so it's available in all projects.

Option C: Project-Specific Setup

Add to your project's .mcp.json:

{
  "mcpServers": {
    "oh-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cloud-atlas-ai/oh-mcp-server"],
      "env": {
        "OH_API_KEY": "your_api_key_here",
        "OH_API_URL": "https://app.openhorizons.me"
      }
    }
  }
}

3. Verify

Restart Claude Code, then ask Claude to test the connection:

Try calling: oh_about

If it works, you'll see OH MCP tools available!

Available Tools

Read Operations

• oh_get_contexts - List all contexts (personal and shared workspaces)
• oh_get_endeavors - Get endeavors (missions, aims, initiatives, tasks) in a context
• oh_get_endeavor - Get details of a specific endeavor with hierarchy
• oh_get_logs - Get recent logs/decisions for an endeavor
• oh_about - Get information about Open Horizons and this MCP server

Write Operations (Endeavors)

• oh_create_endeavor - Create new mission, aim, initiative, or task
• oh_update_endeavor - Update endeavor title and/or description
• oh_archive_endeavor - Archive endeavor (soft delete)
• oh_unarchive_endeavor - Restore an archived endeavor
• oh_set_parent - Change parent of an endeavor (move in hierarchy)
• oh_delete_endeavor - Permanently delete an endeavor

Write Operations (Logging & Learning)

• oh_log_decision - Log decision, note, or progress to an endeavor
• oh_update_log - Update a log entry's content
• oh_delete_log - Delete a log entry
• oh_create_metis_candidate - Surface a pattern/learning for later review (metis = situated judgment)
• oh_create_guardrail_candidate - Surface a constraint/rule that should be enforced

Write Operations (Candidates)

• oh_create_metis_candidate - Surface a pattern/learning for later review
• oh_create_guardrail_candidate - Surface a constraint/rule for later review

Write Operations (Contexts)

• oh_create_context - Create new shared context (workspace)
• oh_update_context - Update context title and/or description
• oh_move_endeavor - Move endeavor to different context
• oh_delete_context - Permanently delete a context
• oh_invite_to_context - Invite user by email with role (editor or viewer)

Core Concepts

Open Horizons uses a four-level alignment hierarchy:

Mission (why you exist)
  └── Aim (outcome you want)
       └── Initiative (how you'll achieve it)
            └── Task (what you do today)

Key Ideas:

• Contexts: Personal or shared spaces where endeavors live
• Endeavors: Any node in the hierarchy (mission, aim, initiative, task)
• Decision logs: Captured reasoning and progress tied to endeavors
• Alignment: Every task traces back to a mission, so you always know why
• Metis: Situated judgment - patterns and learnings captured from real work
• Guardrails: Executable constraints that prevent repeating mistakes

Learning Capture Workflow

When agents discover a reusable insight or constraint during work:

1. Agent creates candidate - Use oh_create_metis_candidate or oh_create_guardrail_candidate to surface it
2. Human reviews in OH app - Candidates appear in the Reflect mode UI at app.openhorizons.me for human review
3. Human promotes with structure - Add structured fields in OH app (violated_expectation, observed_reality, consequence for metis; title and override_protocol for guardrails)
4. Activated knowledge - Promoted items become active metis/guardrails that inform future agent work

This two-step flow ensures quality - agents flag "this matters" moments with near-zero friction, while humans curate what becomes durable knowledge in the OH app.

Use Cases

1. Strategic Coding with Claude Code

Install superego + OH MCP for metacognitive feedback tied to strategic context:

# Install superego (metacognitive advisor)
claude plugin marketplace add cloud-atlas-ai/superego
claude plugin install superego@superego

# Install OH MCP (strategic alignment)
claude plugin marketplace add cloud-atlas-ai/oh-mcp-server
claude plugin install oh-mcp@oh-mcp

# Restart Claude Code, then:
/superego:init
/oh-mcp:setup

Now Claude Code has metacognitive feedback (superego) tied to strategic context (OH MCP). Every decision gets logged back to your alignment framework.

2. AI Swarm Coordination

Use OH MCP in multi-agent systems to:

• Fetch alignment packages before execution
• Log decisions from each agent run
• Maintain governance constraints across swarms
• Create an audit trail of all AI decisions

See the Swarm Alignment architecture for details.

3. Custom AI Tools

Integrate OH MCP into your own AI tools:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

// Your MCP server can call OH API via the oh-mcp tools
// to read context and log decisions

Environment Variables

• OH_API_KEY - Your Open Horizons API key (required)
• OH_API_URL - OH API base URL (default: https://app.openhorizons.me)

Global Installation (Alternative)

If you prefer a global install over npx:

npm install -g @cloud-atlas-ai/oh-mcp-server

# Then use 'oh-mcp' command directly:
claude mcp add oh-mcp -s user \
  -e OH_API_URL=https://app.openhorizons.me \
  -e OH_API_KEY=your_api_key_here \
  -- oh-mcp

Development

# Clone the repo
git clone https://github.com/cloud-atlas-ai/oh-mcp-server.git
cd oh-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run in dev mode
npm run dev

# Test manually
OH_API_KEY=your_key npm start

Troubleshooting

"API key invalid"

• Verify your API key is correct
• Make sure you're using a key from https://app.openhorizons.me/settings/api-keys

"Connection failed"

• Check that https://app.openhorizons.me is accessible
• Verify your firewall/proxy isn't blocking the connection

"MCP server not found" or "/oh-mcp:setup not recognized"

• The /oh-mcp:setup command requires the plugin (see Option A above)
• Without the plugin, use Option B or C for manual setup

"MCP server crashed"

• Check that the dist/index.js file exists (run npm run build if missing)
• Look at Claude Code's MCP logs for error details
• Try running manually: OH_API_KEY=<key> npx @cloud-atlas-ai/oh-mcp-server

Related Projects

• Superego - Metacognitive advisor for Claude Code (pairs perfectly with OH MCP)
• Open Horizons - The strategic alignment platform

License

MIT License - see LICENSE for details.

Support

• Issues: GitHub Issues
• Email: hello@cloudatlas.ai