mcp-inference-bridge
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-inference-bridge
A small Model Context Protocol server that lets an AI assistant (Claude Desktop, Claude Code, Cursor, MCP Inspector) call an existing HTTP image-classification API: classify an image, show a heatmap explaining the prediction, and read the model's metadata.
The server is a thin wrapper. It does no inference itself: it validates the input, calls your API with a timeout, and turns the answer (or the failure) into something the assistant can use.
Research use only. Not a diagnosis and not for clinical decisions. Every tool result carries this disclaimer.
Tools
Tool | Input | Returns |
|
|
|
|
| the heatmap as MCP image content (PNG, shown inline by clients) plus a one-line summary |
| none | model name, version, input size, class names, decision threshold |
All three are read-only and annotated as such.
Failures come back as tool errors written for the assistant, not stack traces:
Situation | Message the assistant sees |
Both or neither image input given |
|
File missing, too large, or not an image | says which, and what is accepted |
API slow |
|
API down |
|
Wrong key |
|
API 4xx | the API's own |
API 5xx | a generic message; the details go to the server log (stderr) only |
Related MCP server: image-understand-mcp
Quick start
Requires Python 3.12+ and uv.
git clone https://github.com/ThuanE3691/mcp-inference-bridge.git
cd mcp-inference-bridge
uv sync --extra demoThe repository includes a tiny stand-in inference API (scikit-learn digits classifier with an occlusion heatmap) so everything can be tried without a real model:
uv run uvicorn demo_api.digits_api:app --port 8765 # terminal 1: the demo API
uv run python -m demo_api.make_samples # writes samples/digit-*.pngThen point an MCP client at the bridge (next section) and ask, for example: "What does the model predict for samples/digit-3.png, and show me why."
Configuration
Everything is read from environment variables. Nothing is hard-coded and no secret is ever written to tool output.
Variable | Required | Default | Meaning |
| yes | Base URL of the inference API | |
| no | Sent as the | |
| no |
| Per-request timeout |
| no |
| Largest accepted image |
The server refuses to start, with a one-line reason, if INFERENCE_API_URL is missing.
Connect a client
Claude Desktop
Edit claude_desktop_config.json (Settings → Developer → Edit Config) and restart
Claude Desktop:
{
"mcpServers": {
"inference": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/mcp-inference-bridge", "run", "mcp-inference-bridge"],
"env": {
"INFERENCE_API_URL": "http://127.0.0.1:8765",
"INFERENCE_API_KEY": "dev-key"
}
}
}
}Cursor
Put the same mcpServers block in .cursor/mcp.json (project) or ~/.cursor/mcp.json
(global).
Claude Code
claude mcp add inference \
-e INFERENCE_API_URL=http://127.0.0.1:8765 -e INFERENCE_API_KEY=dev-key \
-- uv --directory /absolute/path/to/mcp-inference-bridge run mcp-inference-bridgeMCP Inspector
npx @modelcontextprotocol/inspector \
-e INFERENCE_API_URL=http://127.0.0.1:8765 -e INFERENCE_API_KEY=dev-key \
uv --directory /absolute/path/to/mcp-inference-bridge run mcp-inference-bridgeAdd --cli --method tools/list (or --method tools/call --tool-name classify_image --tool-arg image_path=/abs/path/digit-3.png) to drive it from a script.
Checked with
Against the demo API on Windows 11:
MCP Inspector (CLI):
tools/listshows the three tools;classify_imagereturns structured content;explain_predictionreturns animagecontent block (PNG).Claude Code: asked in plain language to classify and explain
samples/digit-3.png, it calledget_model_info,classify_imageandexplain_predictionin that order and described the heatmap it received.
Claude Desktop and Cursor launch the server the same way (stdio), using the config above.
What the API must look like
The bridge expects three endpoints. Paths are constants at the top of
api_client.py; change them there if yours differ.
Endpoint | Request | Response |
|
|
|
|
|
|
|
|
Adding a tool
Add a method to
InferenceClientinapi_client.pythat calls the new endpoint through_request(that is where the timeout and error mapping live).Add a function inside
build_serverinserver.py, decorated with@mcp.tool(title=..., annotations=...). Return a pydantic model for structured data, orImage(...)for a picture.Write the docstring for the assistant: what the tool returns, when to use it, and when to use a sibling tool instead. The docstring is the tool description the model reads.
Add a test in
tests/test_mcp_tools.py. The tests call tools through a real MCP client session, so they check what an assistant would actually receive.
Tests
uv run --extra demo pytesttest_image_input_validation.py: file, base64 and data-URL input; rejected inputs.test_mcp_tools.py: every tool through an in-memory MCP client against a mocked API, including timeouts, connection errors, a rejected key and 4xx/5xx responses.test_stdio_end_to_end.py: starts the demo API, launches the bridge as a stdio subprocess (the way desktop clients do) and runs all three tools for real.
Notes
image_pathreads a file from the machine the server runs on, with the server's permissions. It accepts image files only (checked with Pillow) up toMAX_IMAGE_BYTES.Transport is stdio, for local single-user use. Nothing listens on a network port.
Built on the official Python SDK (
mcp2.x,MCPServer).
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Use your own trained text and picture classification models from any AI assistant.
Run AI-powered analysis on images including moderation, captioning, tagging, and more.
Run AI models, create deployments, and manage predictions via cloud API
Discover, compare, route, and execute machine-accessible capabilities for AI agents.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables LLMs like DeepSeek to understand images by calling external vision models via OpenAI-compatible API. Provides tools to describe images or diagnose connectivity.2-
- AlicenseAqualityCmaintenanceEnables pure text LLMs to understand images by acting as a proxy to vision models via OpenAI-compatible APIs. Supports local files, URLs, and base64 inputs for image analysis.2MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to read COVID-19 lateral flow test results from photographs by calling a deployed computer-vision pipeline, returning verdicts like positive or negative with confidence.MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding assistants without native vision to analyze screenshots, errors, UI designs, and documents through a unified image understanding tool backed by multiple vision model providers. Supports local files, remote URLs, Data URIs, OCR, multi-crop processing, and stdio or HTTP deployment for shared access.512 npmMIT