RAE MCP Server for rae-api.com Integration

Overview

The RAE MCP Server is a lightweight bridge that implements the Model Context Protocol (MCP) used by rae-api.com. It lets you expose any model (OpenAI, Hugging Face, a local LLM behind an HTTP API, etc.) through a consistent MCP-compatible HTTP interface so rae-api.com can call your preferred model when serving the RAE Spanish dictionary features.

This server is useful when you want to run inference on a model you control (for cost, privacy or latency reasons) but still take advantage of rae-api.com’s dictionary, lookup, and conversation orchestration. The MCP server handles request/response translation, streaming support, basic auth, and provides adapter hooks so you can plug in different model backends with minimal code changes.

Features

• Implements a standard MCP-compatible HTTP surface for rae-api.com to call
• Adapter-based backend support (OpenAI, generic HTTP LLM endpoints, local model runners)
• Streaming and non-streaming completion endpoints
• Health and metrics endpoints for monitoring
• Simple configuration via environment variables or JSON config file
• Dockerfile and systemd-friendly startup for deployment

Installation / Configuration

Clone and install:

git clone https://github.com/rae-api-com/rae-mcp.git
cd rae-mcp
npm install

Environment-based configuration (example .env):

# Server
PORT=8080
MCP_BASE_PATH=/mcp

# Select backend: openai | http | custom
MODEL_PROVIDER=openai

# OpenAI backend
OPENAI_API_KEY=sk-...

# Generic HTTP LLM backend (if MODEL_PROVIDER=http)
MODEL_URL=http://127.0.0.1:8081/v1/generate
MODEL_API_KEY=your-model-key

# Optional: basic auth tokens allowed to call this MCP server
API_TOKENS=token1,token2

Start the server:

npm start
# or (development)
node src/index.js

Run with Docker:

docker build -t rae-mcp .
docker run -e MODEL_PROVIDER=openai -e OPENAI_API_KEY=$OPENAI_API_KEY -p 8080:8080 rae-mcp

Config file example (config.json):

{
  "port": 8080,
  "modelProvider": "http",
  "model": {
    "url": "http://localhost:8081/v1/generate",
    "headers": { "Authorization": "Bearer example" }
  },
  "allowedTokens": ["token1","token2"]
}

Available Resources

The server provides a small set of HTTP endpoints useful for integration and monitoring.

Adapter code locations and examples:

• src/adapters/openai.js — OpenAI-compatible adapter
• src/adapters/http.js — Generic HTTP adapter for self-hosted LLMs
• src/adapters/example-custom.js — Template for adding a new backend

To add a custom adapter, implement the adapter interface (init(config), generate(request), stream(request)) and register it in the server bootstrap.

Use Cases

1. Running a private model with rae-api.com

   • Deploy the MCP server pointing at your on-prem or cloud-hosted model (MODEL_PROVIDER=http and MODEL_URL to your model). Configure rae-api.com to use the MCP server base URL. RAE calls will use your model while still leveraging the RAE dictionary lookups.

2. Cost-controlled OpenAI integration

   • Use the OpenAI adapter to route rae-api.com model calls through a central place where you can manage keys, rate limits, and logging without exposing keys directly to rae-api.com. Set MODEL_PROVIDER=openai and provide OPENAI_API_KEY.

3. Hybrid retrieval + generation

   • Use the MCP server to preprocess requests (e.g., inject RAE dictionary entries or retrieval context) before forwarding to the model, or postprocess to enforce token limits and safe completions. This lets you combine RAE lookups with model answers reliably.

4. Local testing and development

   • Run a local LLM or a lightweight mock model behind the HTTP adapter to perform automated testing of rae-api.com integrations without depending on external services.

Example: Basic Completion Request

Curl example for a non-streaming call to the MCP server:

curl -X POST "http://localhost:8080/mcp/complete" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token1" \
  -d '{
    "model": "default",
    "input": "Define 'amistad' and give an example sentence in Spanish.",
    "max_tokens": 200
  }'

Response is an MCP-compatible JSON object containing the model’s text completion and metadata.

Troubleshooting & Tips

• If rae-api.com shows timeouts, increase the model backend timeout or enable streaming to reduce perceived latency.
• Use /health in orchestration (Kubernetes, systemd) to ensure the service is restarted automatically.
• Log and rotate access tokens; prefer short-lived keys and restrict IPs for production deployments.

Repository and source code: https://github.com/rae-api-com/rae-mcp