PrismRelay MCP
Vision First — v0.3.0
PrismRelay gives text-only Agents, including DeepSeek-based workflows, a way to inspect real image pixels through a local stdio MCP server. The Agent remains the primary reasoner; PrismRelay sends the requested images to an external vision provider and returns a visual answer.
Agnes AI is the current backend. PrismRelay is an independent community project and is not affiliated with, endorsed by, or sponsored by Agnes AI.
Release status
| Capability | Status | Suitable for |
|---|---|---|
| Image understanding | Supported, primary workflow | Scene and object questions, screenshots, documents, charts, diagrams, visible text, image comparison |
| Image generation | Experimental | General drafts where provider variation is acceptable |
| Image editing and composition | Experimental | Exploratory edits with manual review |
| Strong Style Skill compliance | Not a claimed capability | Do not promise faithful art direction or native multimodal quality |
PrismRelay does not change the text model into a native multimodal model. It gives the Agent a callable external “eye.” Visual accuracy, latency, and availability still depend on Agnes AI and on the Agent host correctly invoking MCP tools.
Tools
prismrelay_understand_image— inspect, compare, answer questions, read visible text, and interpret screenshots, documents, charts, diagrams, products, or scenes.prismrelay_generate_image— experimental generation with optional references, final dimensions, candidates, and review.prismrelay_edit_image— experimental editing and composition with input roles, preservation hints, and review.
Legacy agnes_* tools remain for compatibility but are not recommended for new workflows.
Requirements
- Node.js 18 or newer
- Your own Agnes Platform account and API key
- An Agent host that supports local stdio MCP tools
- Outbound HTTPS access to
https://apihub.agnes-ai.com/v1or your configured Agnes route
PrismRelay is BYOK: every user supplies their own key and accesses Agnes directly. Do not share accounts, keys, credits, or offer PrismRelay as a resale/proxy service.
Install from GitHub
git clone https://github.com/Arnoldkevin/prismrelay-mcp.git
cd prismrelay-mcp
npm install
export AGNES_API_KEY="your_api_key_here"Persist AGNES_API_KEY using your operating system or shell's secret/environment mechanism. Never paste it into a chat, tracked file, screenshot, or support log.
Codex
node dist/prismrelay-mcp.mjs setup codex --dry-run
node dist/prismrelay-mcp.mjs setup codex --force
node dist/prismrelay-mcp.mjs doctorThis installs the Skill at ~/.agents/skills/prismrelay-images and registers the MCP server as prismrelay.
Claude Code
node dist/prismrelay-mcp.mjs setup claude-code --dry-run
node dist/prismrelay-mcp.mjs setup claude-code --force
node dist/prismrelay-mcp.mjs doctor
claude mcp get prismrelayThis registers a user-scoped stdio server and installs the Skill at ~/.claude/skills/prismrelay-images. Start a new Claude Code session from a shell that exports AGNES_API_KEY, then use /mcp to confirm that the server is connected.
Other Agent hosts
Configure this process in the host's stdio MCP settings:
command: node
args: /absolute/path/to/prismrelay-mcp/dist/prismrelay-mcp.mjs serve
environment passthrough: AGNES_API_KEY, AGNES_BASE_URL, AGNES_OUTPUT_DIRAlso install skills/prismrelay-images in the host's supported Skill directory if it supports Agent Skills. See [Host setup and automatic invocation](docs/HOST_SETUP.md).
DeepSeek Harness plugin
PrismRelay also ships as an installable DeepSeek Harness bundle. It uses Harness's official MCP Client to expose the same local PrismRelay tools; the visual runtime is not duplicated.
export AGNES_API_KEY="your_api_key_here"
npx @deepseek-ai/dsh plugin --profile web add github:Arnoldkevin/prismrelay-mcp
npx @deepseek-ai/dsh --profile web --dump-config
npx @deepseek-ai/dsh webDeepSeek Harness is currently a Developer Preview, so compatibility may need to track upstream breaking changes. See [DeepSeek Harness integration](docs/DEEPSEEK_HARNESS.md) for configuration, removal, and current MCP image-output limitations.
Does it call itself automatically?
Sometimes, but installation is not a guarantee.
MCP makes the tools available. The host model decides whether to invoke them from the request, MCP tool descriptions, the companion Skill, permissions, and its tool-calling implementation. PrismRelay's Skill strongly instructs a text-only Agent to call prismrelay_understand_image whenever a visual task includes a readable image source.
For the most reliable first test, give an explicit local path:
请查看 /absolute/path/to/screenshot.png，告诉我页面当前状态和可见的报错。A local MCP process cannot intercept an opaque image attachment held only inside the host's private conversation payload. If a pasted image is not exposed as a path, save it to disk and provide the path. DeepSeek used through a Claude Code-compatible proxy must also support Claude Code's tool-calling protocol; that behavior is controlled by the proxy/model, not PrismRelay.
Recommended vision tasks
- Ask what is visible in a photo and request evidence for the answer.
- Diagnose a UI screenshot or error dialog.
- Extract headings, totals, dates, or status labels from a clean document image.
- Explain the trend and legend in a chart.
- Compare two product images or two UI screenshots.
- Check whether a poster contains a specified element or visible wording.
Run the repeatable matrix in [Vision evaluation](docs/VISION_EVAL.md) before making reliability claims for a particular Agent host and model combination.
Privacy and data flow
Images are read by the local MCP process and sent to the configured Agnes API for inference. They are not processed entirely on-device. Generated or downloaded results are saved under AGNES_OUTPUT_DIR (default ./outputs). See [Privacy](PRIVACY.md) before using personal, confidential, regulated, or third-party images.
Configuration
| Variable | Required | Default | Purpose |
|---|---|---|---|
AGNES_API_KEY | Yes | None | Agnes API authentication |
AGNES_BASE_URL | No | https://apihub.agnes-ai.com/v1 | Agnes API route |
AGNES_OUTPUT_DIR | No | ./outputs | Downloaded and finalized image directory |
AGNES_TIMEOUT_MS | No | 120000 | Per-request timeout in milliseconds |
AGNES_MAX_RETRIES | No | 3 | Maximum retryable API attempts |
AGNES_MAX_IMAGE_BYTES | No | 26214400 | Input/output image safety limit |
AGNES_EMBED_MAX_BYTES | No | 4194304 | Largest image embedded in an MCP response |
Scope and limitations
- Local stdio MCP only; no remote hosting, shared service, OAuth, billing, or video generation.
- Understanding is delegated to a separate vision model. It may misread small text, blur, occlusion, dense tables, subtle differences, or ambiguous scenes.
- Generation/editing review can identify some failures, but cannot force a provider to follow strong style or layout instructions.
- The current release has automated contract and packaging tests. Users should separately run the live evaluation matrix with their own Agnes key and chosen Agent host.
Development
npm test
npm run smoke
npm run pack:check
npm audit --omit=devLicense and provider terms
PrismRelay's original code is released under the [MIT License](LICENSE). MIT covers this repository's code only; it does not grant rights to Agnes models, APIs, output, documentation, branding, or trademarks.
The Agnes service terms restrict unauthorized resale, sublicensing, or provision of the service to third parties. PrismRelay therefore uses a direct BYOK design and must not be operated as a shared-key proxy or resale service. The public terms do not explicitly name community MCP clients, so this repository does not claim official authorization or endorsement. Read [Third-party notices](THIRD_PARTY_NOTICES.md) and obtain written clarification from Agnes for commercial redistribution models beyond direct BYOK use.