@omni-co/mcp

MCP bridge for connecting local AI clients (Claude Desktop, ChatGPT) to remote Omni MCP servers.

Usage

No installation required. Just update your MCP configuration JSON file to reference this repository as shown in the Claude Desktop example below.

Claude Desktop Configuration

Add the following to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "Omni MCP": {
      "command": "npx",
      "args": ["@omni-co/mcp"],
      "env": {
        "DEBUG": "true",
        "MCP_SERVER_URL": "https://<instance-id>.omniapp.co/mcp/https",
        "MCP_API_KEY": "<YOUR-OMNI-API-KEY>",
        "MCP_MODEL_ID": "<YOUR-OMNI-MODEL-ID>", // Optional: your Omni model ID
        "MCP_TOPIC_NAME": "my-topic", // Optional: limit the MCPs access to a single topic within your model
        "MCP_USER_ID": "user-123", // Optional: unique user identifier - when present, ensures that the user's permissions are respected by the MCP server. All query generation will be completed as that user.
        "MCP_USER_REQUIRED": "true" // Optional: whether user ID is required for the MCP server
      }
    }
  }
}

Environment Variables

• MCP_SERVER_URL: The URL of your Omni MCP server (required)
• MCP_API_KEY: Your Omni API key (required)
• MCP_MODEL_ID: Your Omni model ID (optional)
• MCP_TOPIC_NAME: Topic name to limit MCP access to a single topic within your model (optional)
• MCP_USER_ID: Unique user identifier to be passed as X-MCP-User-ID header (optional). When set, the MCP server will execute all operations as this user, respecting their permissions and access controls. All query generation will be completed in the context of this user's permissions.
• MCP_USER_REQUIRED: Set to "true" to pass X-MCP-User-Required header indicating user ID is required (optional)
• DEBUG: Set to "true" to enable debug logging (optional)

Getting Your Credentials

1. Log in to your Omni instance
2. Navigate to the Settings page
3. Under API Keys - get the API key you want to use
4. Navigate to Develop -> Select the model you want to use. Copy the modelId from the URL
5. Use your instance URL in the format: https://<instance-id>.omniapp.co/mcp/https

Documentation

For more detailed information about Omni MCP:

• Omni MCP with VS Code
• Omni MCP Documentation

How It Works

This package provides two ways to connect to Omni MCP servers:

1. Standard Bridge Mode (stdio)

Acts as a bridge between your local AI client (Claude Desktop, ChatGPT) and the remote Omni MCP server:

1. Receives JSON-RPC requests from your AI client via stdio
2. Forwards them to the Omni MCP server over HTTP/HTTPS
3. Returns the responses back to your AI client via stdio

2. SSE Server Mode (NEW)

Provides a local SSE server that accepts connections from SSE clients and translates their requests to HTTPS for the MCP server:

1. SSE clients connect to the local SSE server endpoint
2. The server forwards requests to the Omni MCP server over HTTPS
3. Responses are sent back to clients via both HTTP responses and SSE events

The bridge handles:

• JSON-RPC protocol communication
• HTTP/HTTPS requests with proper authentication
• Server-Sent Events (SSE) for both input and output
• Client connection management
• Error handling and timeouts

SSE Server Mode

The SSE server mode allows clients to connect via Server-Sent Events and send requests over HTTP. This is useful for web applications and other clients that cannot use stdio or Streamable Http communication.

Starting the SSE Server

# Install the package
npm install @omni-co/mcp

# Run the SSE server
npm run sse-server

# Or run with debug logging
npm run sse-server:debug

Configuring SSE Clients

SSE clients configure their connection by sending headers with their requests:

{
  "omni-sse": {
    "type": "sse",
    "url": "http://localhost:3000/sse",
    "headers": {
      "MCP-API-Key": "omniApiKey",
      "MCP-Model-ID": "modelId",
      "MCP-Server-URL": "https://test.thundersalmon.com",
      "MCP-User-ID": "userID",
      "MCP-User-Required": "true"
    }
  }
}

Note: All configuration is passed via headers from the SSE client. No environment variables are needed for SSE mode.

SSE Server Endpoints

• GET /sse - SSE connection endpoint for receiving events
• POST /sse/messages - JSON-RPC message endpoint

User Authentication

The MCP server supports user-specific authentication:

1. Pass the user ID when connecting:
   • Add MCP-User-ID header to the SSE or StreamableHttp connection

Development

Installation

npm install -g @omni-co/mcp

Or use directly with npx:

npx @omni-co/mcp       # Standard stdio bridge
npx @omni-co/mcp-sse   # SSE server mode

Running Tests

npm test

Running with Coverage

npm run test:coverage

License

MIT