MCP Chat

A React/Next.js web app that gives you a browser chat UI for an LLM running on the server (via Ollama), with the model able to call tools exposed by a Node MCP server.

Under the hood:

1. The MCP server (src/server.js) reads its available tools from tools.js.
2. It sends those tool definitions to a small local model via Ollama.
3. It executes any tool calls the model requests.
4. It feeds the tool results back to the model and returns the final reply.
5. The web app never does any of this itself — it just calls the MCP server.

Architecture

flowchart LR
    subgraph Clients[" "]
        direction TB
        Browser["Browser<br/>(page.js)"]
        OtherClient["Other MCP clients<br/>(Claude Desktop, etc.)"]
    end

    Browser -- "fetch, same-origin" --> Route["Next.js<br/>/api/chat route<br/>(thin proxy)"]
    OtherClient -- "MCP protocol" --> Server
    Route -- "POST :3939/chat" --> Server

    subgraph Server["MCP server process (src/server.js)"]
        direction TB
        MCP["POST /mcp<br/>(Streamable HTTP,<br/>real MCP protocol)"]
        Chat["POST /chat<br/>(plain REST)"]
        Tools["tools.js +<br/>ollamaLoop.js"]
        Chat --> Tools
    end

    Tools -- "plain HTTP, not MCP<br/>POST :11434/api/chat" --> Ollama["Ollama (LLM)"]

The web app never talks to Ollama. The Next.js /api/chat route (web/src/app/api/chat/route.js) is a thin same-origin proxy — its only job is forwarding the browser's request to the MCP server's /chat endpoint and returning the response. It holds no Ollama client code and no tool-calling logic.

All of that lives inside src/server.js, the MCP server process, which exposes two HTTP endpoints:

• POST /mcp — the actual MCP protocol (Streamable HTTP). Any real MCP client (Claude Desktop, another agent, etc.) can connect here to list/call the tools directly, with no Ollama involved at all.
• POST /chat — a plain REST endpoint, used only by our own web app. It reads tool definitions straight from tools.js (in-process, no MCP round-trip needed since it's the same process), then runs the Ollama tool-calling loop (src/ollamaLoop.js): send messages + tool defs to Ollama's /api/chat, execute any requested tool calls locally, feed results back, repeat until Ollama replies with plain text.

So Ollama is purely an implementation detail of the MCP server — nothing outside src/server.js (and certainly not the browser or the Next.js route) ever calls it directly.

Available tools

Defined in src/tools.js, exposed to the model via the MCP server:

• get_current_time — current server date/time.
• calculate — evaluates a basic arithmetic expression.
• list_directory — lists files/folders relative to the server's working directory.
• read_readme — reads this README (or web/README.md), so the model can explain how the app works, its architecture, or how to run it.

Setup

npm install
cd web && npm install && cd ..

# install Ollama (macOS): https://ollama.com/download
brew install ollama
ollama serve &                # starts the Ollama daemon on :11434
ollama pull llama3.2:3b       # small model with tool-calling support

Other small tool-capable models that work too: qwen2.5:3b, mistral-nemo. Override with OLLAMA_MODEL=qwen2.5:3b.

Run the MCP server

npm run server

Starts the MCP server on http://localhost:3939 — /mcp (Streamable HTTP MCP protocol) and /chat (plain REST, runs the Ollama loop) both live here.

Run the web chat

cd web && npm run dev

Open http://localhost:3000. The page posts to its own /api/chat route, which just proxies to the MCP server's /chat endpoint. Requires npm run server (above) and Ollama to be running.

Files

• src/tools.js — tool definitions/handlers, registered on the MCP server.
• src/server.js — the MCP server: /mcp (Streamable HTTP MCP protocol) and /chat (REST, runs the Ollama loop).
• src/ollamaLoop.js — talks to Ollama's /api/chat, runs the tool-calling loop. Used only by src/server.js.
• web/src/app/page.js — top-level page, renders ChatWindow.
• web/src/app/api/chat/route.js — thin same-origin proxy to the MCP server's /chat.
• web/src/hooks/useChat.js — conversation state + /api/chat calls, used by ChatWindow.
• web/src/components/ChatWindow.jsx — assembles the chat UI from MessageList + ChatInput.
• web/src/components/MessageList.jsx / ChatMessage.jsx / WelcomeMessage.jsx — message history rendering.
• web/src/components/ChatInput.jsx — the textarea + Send/Cancel form.

Testing

npm test              # MCP server + tools (Node's built-in test runner)
cd web && npm test     # React components + useChat hook (Vitest + Testing Library)

• src/tools.test.js / src/server.test.js — tool handlers, and an integration test that spins up the MCP server on an ephemeral port and talks to it over real Streamable HTTP.
• web/src/**/*.test.jsx / *.test.js — component and hook tests, colocated with the code they test.

Environment variables

• OLLAMA_HOST (default http://localhost:11434) — used by src/server.js.
• OLLAMA_MODEL (default llama3.2:3b) — used by src/server.js.
• PORT (default 3939) — MCP server port.
• MCP_SERVER_CHAT_URL (default http://localhost:3939/chat) — used by web/'s /api/chat proxy route.