Skip to content

Connecting Assistants

Jump to bottom
Beat edited this page Aug 28, 2026 · 2 revisions

Connecting Assistants

The server speaks to assistants two ways: MCP (Streamable HTTP) for clients that support it, and the REST tool gateway + OpenAPI spec for everything else. Both expose the same 33 tools.

Your access key lives at <data folder>/accessKey.txt — data/ at the project root by default (printed on server startup).

MCP clients

Connect to:

http://localhost:3000/mcp?key=YOUR_KEY

Claude Code

claude mcp add --transport http omnivox "http://localhost:3000/mcp?key=YOUR_KEY"

Claude Desktop / other Streamable HTTP clients

Add a remote MCP server with the URL above. For clients that configure JSON:

{
  "mcpServers": {
    "omnivox": {
      "type": "http",
      "url": "http://localhost:3000/mcp?key=YOUR_KEY"
    }
  }
}

stdio (deprecated)

npm run start:stdio lets an MCP client launch the server as a subprocess over stdin/stdout. It works, but HTTP mode is the supported path — no access key handling, no REST gateway, and the client has to manage the process. See AGENT_SETUP.md in the repo if you really need it.

Non-MCP assistants (OpenAPI / JSON tool definitions)

Any assistant or agent framework that accepts JSON-described tools can use the gateway directly:

  • GET /openapi.json — a complete OpenAPI 3.1 spec: one POST /tools/{name} operation per tool, with input schemas, descriptions, and x-readOnly markers. Feed it to anything that imports OpenAPI (custom GPT actions, Open WebUI tool servers, LangChain OpenAPI toolkits, etc.).
  • GET /tools — the same catalog as raw JSON: name, title, description, annotations, and JSON Schema inputSchema per tool. Convenient when you're mapping tools into a framework's own format (e.g. OpenAI function calling).

Calls are plain HTTP:

curl -X POST http://localhost:3000/tools/get-grades-summary \
  -H "x-mcp-auth: YOUR_KEY" -d '{}'

Authentication works with either header (the OpenAPI spec declares Bearer):

x-mcp-auth: YOUR_KEY
Authorization: Bearer YOUR_KEY

Tool results come back as the MCP-style content payload (text blocks). The gateway accepts JSON bodies regardless of Content-Type.

Giving the assistant context

The repo's SKILL.md is a ready-made system-prompt companion: it describes every tool, the course_id / term_id conventions, delta annotations, and the workflows that combine tools well (checking for new grades, tracking deadlines, triaging MIO). If your assistant supports skills or custom instructions, hand it that file.

Exposure checklist

If the assistant isn't on the same machine as the server, don't just open port 3000 to the internet — put TLS in front and read the security precautions. The access key in these URLs is your whole session.

Clone this wiki locally