Always Obvious MCP Server (Beta)

MCP (Model Context Protocol) server for integrating Always Obvious platform with Claude Desktop.

⚠️ Beta Software: This MCP server is currently in beta. While we strive for stability, you may encounter occasional issues. Please report any problems to help us improve.

🚀 Latest Features (v0.33.10)

Strategic Planning & Task Management

• Gravity Plan Tasks: Complete task management aligned with OKRs and strategic contexts
• Area Management: Organize tasks by functional areas (Product, Sales, Marketing, etc.)
• Bulk Operations: Efficiently manage multiple tasks for sprint planning

Company & Contact Management

• Companies Database: Track companies with segment associations and business metrics
• Credibility Tracking: Manage testimonials, case studies, and awards as proof points
• Contact Management: Full CRM capabilities with role tracking and relationship strength

OKR Management

• Complete OKR v2 Support: All fields including scoring, corporate objectives, and relationships
• Direct Navigation: Click links to open items directly in the web app
• Rich Display: See relationships, hierarchies, and progress at a glance
• Batch Operations: Update multiple OKRs simultaneously

Research & Intelligence

• AI-Powered Research: Capture and organize market intelligence
• Segment Analysis: Deep market analysis with competitive positioning
• Proposition Development: Value proposition creation and scoring

For complete version history, see the CHANGELOG.

🔐 Security

• API Key Authentication: Use API keys instead of passwords for better security
• Organization Name Matching: Connect using organization names with fuzzy matching
• No Password Storage: Credentials are never stored, only used to obtain session tokens

Design Principles

1. Start Simple, Scale Later: Begin with minimal viable functionality, architecture supports future expansion
2. Conversation-First Design: Tools designed for natural language interaction, not API replication
3. Draft-Then-Commit Pattern: All changes staged locally until explicitly committed
4. Context Awareness: Server maintains organization and user context throughout session
5. Fail-Safe Operations: Read operations are safe, write operations require explicit confirmation
6. Incremental Tool Addition: New tools can be added without breaking existing ones
7. Environment Flexibility: Easy switching between dev/UAT/production

Setup

Installation Options

Option 1: Quick Start with npx (No Installation)

# Configure Claude Desktop to use npx (one-time setup)

Add to your Claude Desktop config file:

{
  "mcpServers": {
    "always-obvious": {
      "command": "npx",
      "args": ["@cormirus/always-obvious-mcp@latest"],
      "env": {
        "ALWAYS_OBVIOUS_API_KEY": "your-api-key-here"  // Optional
      }
    }
  }
}

This will always use the latest version automatically!

Option 2: NPM Global Install (Recommended for Regular Use)

npm install -g @cormirus/always-obvious-mcp

# Run automated setup
always-obvious-mcp-setup

The setup script will automatically configure Claude Desktop for you.

Automatic Update Notifications: The MCP server checks for updates every 3 hours and will notify you when a new version is available. Just run npm update -g @cormirus/always-obvious-mcp to update!

Option 3: Manual Installation

cd mcp-server
npm install
npm run build

Then manually add to Claude Desktop config file:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "always-obvious": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"]
    }
  }
}

API Key Configuration

You have three options for configuring your API key:

Option 1: Pass it in Chat (Simplest)

Simply provide your API key when connecting in Claude:

"Connect with API key ao_1234567890abcdef..."

Option 2: Add to Claude Desktop Config (Most Convenient)

Add your API key directly to the Claude Desktop config file for automatic authentication:

{
  "mcpServers": {
    "always-obvious": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "ALWAYS_OBVIOUS_API_KEY": "ao_your_api_key_here"
      }
    }
  }
}

With this setup, you can simply say "Connect to Always Obvious" without providing the key each time.

Option 3: Environment Files (For UAT/Local Development)

For non-production environments, you can store API keys in environment files:

UAT Environment (~/.always-obvious/.env.uat):

API_URL=https://always-obvious-backend-uat.europe-west2.run.app
FRONTEND_URL=https://always-obvious-frontend-uat.europe-west2.run.app
ALWAYS_OBVIOUS_API_KEY=ao_your_uat_api_key_here

Local Development (~/.always-obvious/.env.local):

API_URL=http://localhost:8000
FRONTEND_URL=http://localhost:3000
ALWAYS_OBVIOUS_API_KEY=ao_your_local_api_key_here

Then connect with: "Connect to Always Obvious using uat" or "Connect to Always Obvious using local"

Usage

After configuring Claude Desktop, you can use these commands in conversation:

Authentication Methods

If API Key is Pre-configured (in Claude config or env file)

# Production (default)
"Connect to Always Obvious"
"Connect to my organization"

# Specific environment
"Connect to Always Obvious using uat"
"Connect to Always Obvious using local"

If Providing API Key in Chat

# Default (production environment)
"Connect to my Always Obvious organization with API key ao_1234567890..."
"Connect to Acme Corp with API key ao_1234567890..."

# Specific environment
"Connect with API key ao_1234567890... to uat"
"Connect with API key ao_1234567890... to local"

Environment Selection

The MCP server supports multiple environments:

• production (default): Production API at https://app.alwaysobvious.com
• uat: UAT environment for testing
• local: Local development at http://localhost:8000

You can specify the environment when connecting:

"Connect with API key [key] to uat"     # Connect to UAT environment
"Connect with API key [key] to local"   # Connect to local development
"Connect with API key [key]"            # Default to production

Important: Always start a new chat session when switching environments to avoid mixing data from different environments.

Using Email/Password

"Connect to my Always Obvious organization with email and password"
"Connect to Acme Corp" (then provide credentials when prompted)

Organization Selection

• Organization names support fuzzy matching: "Connect to Acme" will match "Acme Corporation"
• If multiple matches exist, you'll be prompted to be more specific
• You can always use the exact organization ID if needed

Common Workflows & Examples

Quick Start: Your First Session

1. "Connect to Always Obvious"
2. "Show me our current OKRs"
3. "Create an OKR for improving customer satisfaction"
4. "Add a key result to increase NPS from 7 to 9"
5. "Assign Philip as the owner"
6. "Update progress to 75%"

Example: Complete Market Analysis

"List all our market segments"
"Show details for the enterprise segment"
"What propositions do we have for enterprise?"
"Rate the AI consulting proposition as High relevance for enterprise"
"Find all enterprise companies with over 500 employees"
"Create an account plan for the top opportunity"

Example: Strategic Planning Session

"What's our organization's vision and mission?"
"Show me the current planning cycle"
"List all OKRs for this quarter"
"Which OKRs are at risk?"
"Create a task to review the at-risk OKRs"
"Assign it to the strategy team"

Example: Research & Intelligence

"Save research about competitor pricing strategies in the enterprise segment"
"Search for all research about AI adoption"
"Get research notes for TechCorp"
"Find research tagged with 'market-trends'"

Working with OKRs

1. List OKRs:

   • "Show me my OKRs"
   • "List OKRs for Q1 2025"

2. Create OKRs:

   • "Create a new OKR: Improve customer satisfaction by 20%"
   • "Add a key result to track NPS score from 7 to 9"

3. Update Progress:

   • "Update the NPS score progress to 8.2"
   • "Mark the customer onboarding OKR as completed"

Working with Organization Essence

1. View Organization Essence:

   • "Show me our organization essence"
   • "What's our vision and mission?"

2. Develop Organization Essence:

   • "Let's work on defining our credo"
   • "Help me articulate our vision for the next 5 years"
   • "Update our mission statement to reflect our new focus"

3. Get Strategic Context:

   • "Show me our full strategic context"
   • "What's our strategic foundation?"

Working with Strategic Narratives

1. View Strategic Narratives:

   • "Show me the strategic narrative for Q1 2025"
   • "List all planning cycles with their narratives"

2. Develop Strategic Narratives:

   • "Let's draft a strategic narrative for our annual plan"
   • "Help me refine the narrative for Q2 based on Q1 learnings"
   • "Finalize the strategic narrative we've been working on"

Advanced Configuration

Custom Environment Files for UAT Testers

If you're a UAT tester or need to connect to a specific environment without access to the source code:

Option 1: Claude Config Directory

Create an environment file in your Claude config directory:

Mac:

echo "API_URL=https://always-obvious-backend-uat-fnm2bpuzfq-nw.a.run.app" > ~/Library/Application\ Support/Claude/.env.uat

Windows:

echo API_URL=https://always-obvious-backend-uat-fnm2bpuzfq-nw.a.run.app > %APPDATA%\Claude\.env.uat

Option 2: User Home Directory

Create a .always-obvious folder in your home directory:

mkdir -p ~/.always-obvious
echo "API_URL=https://always-obvious-backend-uat-fnm2bpuzfq-nw.a.run.app" > ~/.always-obvious/.env.uat

Then connect using:

"Connect with API key [your-key] to uat"

Environment File Search Order

The MCP server looks for environment files in this order:

1. Claude config directory (e.g., ~/Library/Application Support/Claude/.env.{environment})
2. User home directory (e.g., ~/.always-obvious/.env.{environment})
3. MCP server installation directory (for developers)

The first file found is used.

Development

Running in Development Mode

npm run dev

Building for Production

npm run build

Adding New Tools

1. Define tool schema in src/index.ts tools/list handler
2. Implement handler in tools/call switch statement
3. Add service logic in appropriate module (e.g., src/tools/okr.ts)
4. Test with Claude Desktop
5. Document usage examples

Tool Naming Conventions

• Use action verbs: list_, create_, update_, delete_
• Be specific: create_basic_okr not just create
• Group related: okr_list, okr_create, okr_update

Current Tools

Authentication

• connect_to_org - Authenticate with email/password and select organization
• connect_with_api_key - Authenticate with API key (more secure)
• select_organization - Switch between organizations (supports name matching)
• get_current_context - Check current connection status

OKR Management

• list_okrs - List OKRs with optional filtering
• get_okr_details - Get detailed information about a specific OKR
• create_okr - Create an OKR with objective and optional key results
• update_okr - Update an existing OKR
• delete_okr - Delete an OKR and all its key results
• add_key_result - Add a key result to an existing OKR
• update_key_result - Update a key result including assigning DRIs
• delete_key_result - Delete a key result from an OKR
• update_progress - Update the progress of a key result
• set_okr_parent - Set or remove the parent OKR for hierarchy
• get_okr_hierarchy - View the hierarchical structure of an OKR
• create_okr_relationship - Create cross-functional relationships between OKRs
• list_okr_relationships - List all relationships for an OKR
• delete_okr_relationship - Remove a relationship between OKRs

Planning & Strategy

• list_planning_cycles - View available planning cycles
• list_all_planning_cycles - List all planning cycles with strategic narratives
• get_strategic_narrative - Get strategic narratives for planning cycles
• draft_strategic_narrative - Draft or update a strategic narrative
• finalize_strategic_narrative - Finalize a strategic narrative

Organization Management

• list_organization_members - List all members in your organization with roles
• get_organization_essence - Get Organization Essence (vision, mission, credo, etc.)
• update_organization_essence - Update Organization Essence fields
• get_strategic_context - Get full strategic context including essence and cycles

Roadmap

Phase 1: Basic Pipeline ✅ COMPLETE

• ✅ Authentication and org connection
• ✅ List OKRs
• ✅ Create basic OKR
• ✅ API key authentication (more secure)
• ✅ Organization name matching

Phase 2: Enhanced OKR Management ✅ COMPLETE

• ✅ Add key results to OKRs
• ✅ Update existing OKRs
• ✅ Delete OKRs
• ✅ Link parent-child OKRs
• ✅ Cross-functional OKR relationships
• ✅ Progress tracking and updates
• ✅ DRI (Directly Responsible Individual) assignment

Phase 3: Strategic Planning ✅ COMPLETE

• ✅ Organization Essence management (vision, mission, credo)
• ✅ Strategic narrative development for planning cycles
• ✅ Strategic context aggregation
• ✅ Planning cycle management
• ✅ Iterative narrative refinement

Phase 4: Future Enhancements

• [ ] Draft management and local staging
• [ ] Batch operations for bulk updates
• [ ] AI-powered OKR suggestions
• [ ] Advanced analytics and insights
• [ ] Integration with research tools

Deployment & Distribution

Publishing to NPM

# Build the project
npm run build

# Publish to NPM registry
npm publish

Users can then install with:

npm install -g @always-obvious/mcp-server

Distributing to End Users

1. Technical Users: Direct them to use NPM installation
2. Non-Technical Users:
   • Provide pre-built binaries or installers
   • Consider creating a desktop app wrapper
   • Offer managed cloud deployment

Security Best Practices

1. Never hardcode credentials - Use environment variables or secure storage
2. Use API keys over passwords - Generate from Always Obvious account settings
3. Rotate keys regularly - Implement key rotation policies
4. Limit key permissions - Use read-only keys where possible

Source Code

The source code for this MCP server is part of the Always Obvious Strategy Platform:

• GitHub Repository: https://github.com/Cormirus/obvious-choice-strategy-platform (private)
• MCP Server Location: /mcp-server folder within the repository
• Changelog: Available in the repository at /mcp-server/CHANGELOG.md

Troubleshooting

Server not appearing in Claude Desktop

1. Check config file path is correct
2. Ensure absolute path to index.js
3. Restart Claude Desktop after config changes

Authentication failures

1. Verify API_URL is correct for your environment
2. Check backend is running (for local development)
3. Ensure credentials are correct
4. For API keys, ensure they're valid and not expired

Tool execution errors

Check Claude Desktop logs:

• Mac: ~/Library/Logs/Claude/
• Windows: %APPDATA%\Claude\logs\