Skip to main content

​
Usage

omnara mcp [OPTIONS]
Runs the MCP (Model Context Protocol) stdio server for integration with MCP-compatible clients like Claude Desktop, Cursor, Cline, and other AI coding assistants.

​
Options

​
--api-key
string
required
API key for authentication
​
--permission-tool
boolean
Enable Claude Code permission prompt tool
​
--git-diff
boolean
Enable automatic git diff capture for all messages
​
--agent-instance-id
string
Use existing agent instance instead of creating new one
​
--disable-tools
boolean
Disable all tools except the permission tool

​
Examples

# Start MCP server
omnara mcp --api-key YOUR_KEY

​
MCP Client Configuration

​
Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
claude_desktop_config.json
{
  "mcpServers": {
    "omnara": {
      "command": "omnara",
      "args": ["mcp", "--api-key", "YOUR_API_KEY"]
    }
  }
}

​
Cursor

Edit .cursorrules or Cursor settings: 
{
  "mcpServers": {
    "omnara": {
      "type": "stdio",
      "command": "omnara",
      "args": ["mcp", "--api-key", "YOUR_API_KEY", "--git-diff"]
    }
  }
}

​
Using pipx

For pipx installations: 
{
  "mcpServers": {
    "omnara": {
      "command": "pipx",
      "args": ["run", "--no-cache", "omnara", "mcp", "--api-key", "YOUR_API_KEY"]
    }
  }
}

​
Available Tools

The MCP server provides these tools to AI agents:
  • log_step
  • ask_question
  • end_session
  • approve (optional)
Purpose: Log high-level steps the agent is performingParameters:
  • step_description (required): What the agent is doing
  • agent_instance_id (optional): Instance ID
Returns:
  • agent_instance_id: Session identifier
  • step_number: Sequential step count
  • user_feedback: List of queued user messages
Key Feature: Returns pending user feedback with every step

​
Git Diff Capture

When --git-diff is enabled:
1

Initialization

Captures initial git commit hash at startup
2

Diff Generation

On every log_step and ask_question call, generates diff showing all changes from initial commit to current state
3

Worktree Exclusion

Automatically excludes other git worktrees from the diff
4

Untracked Files

Includes untracked files in diff-like format
Use case: Automatically track code changes without manual git commands. The diff is attached to every message sent to the dashboard.

​
Permission Tool

Enable with --permission-tool to route Claude Code permission prompts through the Omnara dashboard: 
omnara mcp --api-key YOUR_KEY --permission-tool
How it works:
  1. Claude Code asks for permission (e.g., “Run this bash command?”)
  2. Request is sent to Omnara MCP server via approve tool
  3. Dashboard shows permission prompt to user
  4. User approves/denies via dashboard
  5. Response sent back to Claude Code
  6. Permission decision cached for session
Benefits:
  • Approve Claude Code actions remotely
  • Review permission requests before approval
  • Session-wide permission caching

​
Tool Disabling

Use --disable-tools to disable all tools except the permission tool: 
omnara mcp --api-key YOUR_KEY --permission-tool --disable-tools
Use case: When using Omnara purely for permission prompts with Claude Code, reduce overhead by disabling logging/question tools.

​
How It Works

  1. Stdio Server: Communicates via stdin/stdout using MCP protocol
  2. Tool Registration: Registers available tools with the MCP client
  3. Request Handling: Processes tool calls from AI agents
  4. API Integration: Forwards messages to Omnara API for storage/dashboard sync
  5. Response Delivery: Returns results to AI agent via stdio

​
Supported Clients

Claude Desktop

Stdio transport

Claude Code

Stdio transport

Cursor

HTTP/Stdio transport

Cline

Stdio transport

Windsurf

SSE transport

Custom Clients

Any MCP-compatible client

​
Authentication

Uses JWT-based authentication with custom RSA keys:
  • API key is a JWT token with user_id claim
  • Weaker RSA keys used for shorter API keys (design tradeoff)
  • All operations scoped to authenticated user
  • Keys should be kept secure despite weaker crypto
Store API keys securely. While the MCP server uses weaker RSA for shorter keys, they still provide user-level access to your Omnara account.

MCP Clients Integration

Detailed client configuration examples

Python SDK

Programmatic access to same functionality