Connhex MCP Server

An MCP server that exposes Connhex APIs as tools.

Prerequisites

• Python 3.11+
• A Connhex account with access to your instance

Configure your MCP client

Add the server to your MCP client configuration.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "connhex": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/compiuta-origin/connhex-mcp-server",
        "connhex-mcp"
      ],
      "env": {
        "CONNHEX_INSTANCE_URL": "<connhex-instance-url>",
        "CONNHEX_USERNAME": "[email protected]",
        "CONNHEX_PASSWORD": "your-password"
      }
    }
  }
}

Authentication

The server requires CONNHEX_INSTANCE_URL pointing to your Connhex instance.

Authentication is configured via CONNHEX_AUTH_TYPE (defaults to credentials):

Transport

By default the server uses stdio. You can select a different transport by appending --transport to the args array:

"args": [
  "--from",
  "git+https://github.com/compiuta-origin/connhex-mcp-server",
  "connhex-mcp",
  "--transport",
  "streamable-http"
]

Available transports: stdio, http, sse, streamable-http.

Usage Examples

Once the MCP server is connected, you can ask your AI assistant things like:

• "Who am I logged in as?"
• "List all my resources of type <type>"
• "Show me the last 10 messages from thing <thing-id>"
• "Read messages from channel <channel-id> between yesterday and today"

Testing with MCP Inspector

You can test the server locally using MCP Inspector (requires Node.js):

export CONNHEX_INSTANCE_URL=<connhex-instance-url>
export [email protected]
export CONNHEX_PASSWORD=your-password
./scripts/start-mcp-inspector.sh

For token-based auth:

export CONNHEX_INSTANCE_URL=<connhex-instance-url>
export CONNHEX_AUTH_TYPE=token
export CONNHEX_BEARER_TOKEN=your-token
./scripts/start-mcp-inspector.sh

This opens a browser UI where you can interactively call tools and inspect responses.

Development

Clone the repo and install dependencies:

git clone https://github.com/compiuta-origin/connhex-mcp-server.git
cd connhex-mcp-server
uv sync --dev

Run the server locally:

uv run connhex-mcp

Run tests and linting:

uv run pytest
uv run ruff check .