RanchHand — OpenAI-compatible MCP Server

RanchHand is a minimal MCP server that fronts an OpenAI-style API. It works great with Ollama's OpenAI-compatible endpoints (http://localhost:11434/v1) and should work with other OpenAI-compatible backends.

Features

Tools:
- openai_models_list → GET /v1/models
- openai_chat_completions → POST /v1/chat/completions
- openai_embeddings_create → POST /v1/embeddings
- Optional HTTP ingest on localhost:41414 (bind 127.0.0.1): POST /ingest/slack
Config via env:
- OAI_BASE (default http://localhost:11434/v1)
- OAI_API_KEY (optional; some backends ignore it, Ollama allows any value)
- OAI_DEFAULT_MODEL (fallback model name, e.g. llama3:latest)
- OAI_TIMEOUT_MS (optional request timeout)

Run (standalone)

# Example with Ollama running locally export OAI_BASE=http://localhost:11434/v1 export OAI_DEFAULT_MODEL=llama3:latest node server.mjs

HTTP Ingest Service

node http.mjs # Binds to 127.0.0.1:41414 # Shared secret is created at ~/.threadweaverinc/auth/shared_secret.txt on first run

Example request:

SECRET=$(cat ~/.threadweaverinc/auth/shared_secret.txt) curl -s -X POST http://127.0.0.1:41414/ingest/slack \ -H "Content-Type: application/json" \ -H "X-Ranchhand-Token: $SECRET" \ -d '{ "namespace":"slack:T123:C456", "channel":{"teamId":"T123","channelId":"C456"}, "items":[{"ts":"1234.5678","text":"Hello world","userName":"Dan"}] }'

MCP Tools

openai_models_list
- Input: {}
- Output: OpenAI-shaped { data: [{ id, object, ... }] }
openai_chat_completions
- Input: { model?: string, messages: [{ role: 'user'|'system'|'assistant', content: string }], temperature?, top_p?, max_tokens? }
- Output: OpenAI-shaped chat completion response (single-shot; streaming TBD)
openai_embeddings_create
- Input: { model?: string, input: string | string[] }
- Output: OpenAI-shaped embeddings response

Claude/Codex (MCP)

Point your MCP config to:

{ "mcpServers": { "ranchhand": { "command": "node", "args": ["/absolute/path/to/server.mjs"], "env": { "OAI_BASE": "http://localhost:11434/v1", "OAI_DEFAULT_MODEL": "llama3:latest" } } } }

Notes

Streaming chat completions are not implemented yet (single response per call). If your backend requires streaming, we can add an incremental content pattern that MCP clients can consume.
RanchHand passes through OpenAI-style payloads and shapes outputs to be OpenAI-compatible, but exact metadata (usage, token counts) depends on the backend.
HTTP ingest is currently an acknowledgment stub (counts + sample). Chunking/embedding/upsert will be wired next; design is pluggable for local store or Qdrant.

Deploy Server

HTTP connection URL

-

security - not tested

F

license - not found

-

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

Enables interaction with OpenAI-compatible APIs (like Ollama) through MCP tools. Provides access to chat completions, model listings, and embeddings generation from local or remote OpenAI-style endpoints.

RanchHand