mcp-portal
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-portal read src/config.py and src/env.py and tell me which one defines the retry limit"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-portal
mcp-portal is a stdio Model Context Protocol server that lets a frontier agent (Claude Code, Codex, Cursor, or any MCP host) delegate two jobs to the Cursor CLI on its own quota: bounded bulk_read (read explicitly selected files, answer with verified quotes) and code_write (generate boilerplate from a reference file + spec; the server writes the target file). Python stdlib only—no Node runtime and no MCP SDK dependency.
On 2026-09-08, composer-2.5-fast generated roughly 5× faster than a frontier model on the same brief (line-rate measurement). Cursor quota is separate from the host model's.
Quick start
uvx mcp-portalAlso available as pipx install mcp-portal / pip install mcp-portal, and listed in the
MCP Registry as io.github.apollion69/mcp-portal.
To run the development head instead of the release:
uvx --from git+https://github.com/apollion69/mcp-portal mcp-portalRequirements: Python 3.10+, the Cursor CLI (cursor-agent) installed and logged in.
Doctor (CLI inventory, no model call):
mcp-portal-doctorRelated MCP server: cursor-mcp-bridge
Configure per host
Claude Code
claude mcp add --scope user mcp-portal -- uvx mcp-portalCodex (~/.codex/config.toml)
[mcp_servers.mcp-portal]
command = "uvx"
args = ["mcp-portal"]
tool_timeout_sec = 150Cursor (~/.cursor/mcp.json)
{
"mcpServers": {
"mcp-portal": {
"command": "uvx",
"args": ["mcp-portal"]
}
}
}VS Code (.vscode/mcp.json, servers key)
{
"servers": {
"mcp-portal": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-portal"]
}
}
}Generic mcpServers JSON
{
"mcpServers": {
"mcp-portal": {
"command": "uvx",
"args": ["mcp-portal"]
}
}
}Environment (optional):
Variable | Purpose |
| Cache, receipts, evidence (default |
| Path to |
Tools
bulk_read
Argument | Required | Description |
| yes | 1–16 file paths (relative to |
| yes | Question answered only from those files |
| no | Common root; default = longest common parent of |
| no | Override model; policy applies when omitted |
Returns status, run_id, answer.findings[] (file, start, end, quote, fact), gaps[], metrics, model_decision.
code_write
Argument | Required | Description |
| yes | What to generate |
| yes | Style/context reference file |
| no | If set, server writes this path |
| no | Override model |
Returns generated code, optional bytes_written, run_id, metrics.
status
No arguments. Returns CLI path, auth hint, default model, policy summary, cache location, receipt counters.
Model policy
Shipped in model-policy.json (package data). Defaults:
Prefer Cursor-native models (
composer-2.5, thencursor-grok-*)Strip
-fastsuffixes (never auto-select fast variants)Other vendors only when explicitly requested and listed by
cursor-agent --list-models
Override by editing model-policy.json in the installed package or setting policy fields via a custom file at MCP_PORTAL_HOME (future) — today, replace the package file or patch preferred in your fork. Each tool result includes model_decision.reason (default_preferred, fast_suffix_stripped, cursor_native_explicit, explicit_other_vendor, requested_unavailable_fallback).
How it works
Authorize — Server reads only listed paths; blocks credential-like paths and secret patterns.
Manifest — Request JSON includes per-file SHA-256 hashes.
Isolate — Cursor CLI runs with fresh
CURSOR_CONFIG_DIR, deny-all permissions,--mode ask, sandbox enabled.Verify — Every
quoteinbulk_readanswers must appear verbatim in the cited line range; bad citations are dropped or fail closed.Evidence — Per-run directory under
MCP_PORTAL_HOME/runs/<run_id>/with manifest (hashes, metrics; not full source).Budgets — 16 files, 128 KiB combined input, 90s timeout, bounded stdio frames.
Windows
On Windows, the delegate uses a local Cursor CLI run when either:
MCP_PORTAL_CLIpoints at an executable (including test stubs), orcursor-agent/agentis found onPATHand is a real file.
Otherwise it falls back to the wsl.exe bridge into Ubuntu/WSL (python3 -m mcp_portal.delegate --worker). Force either mode with MCP_PORTAL_BACKEND=local or MCP_PORTAL_BACKEND=wsl.
MCP config can use native
uvx mcp-portalwhen the CLI is on PATH, orwsl.exe+uvx mcp-portalwhen it is notHelpers in
clients/windows/(delegate.ps1,parse_read.ps1)MCP_PORTAL_WORKERoverrides the default WSL worker commandMCP_PORTAL_WSL_CDsets the WSL working directory (default~)
Optional Claude Code routing hook
Install read gate + skill (generic, transactional):
python3 -m mcp_portal.install_router prepare --client claude --python python3 \
--state-root ~/.cache/mcp-portal/router-tx --shell bash --command-shell bash
# then apply with the printed transaction idSee docs/skills/cursor-bulk-reader/SKILL.md for agent-facing guidance. The router blocks or warns on large full-file reads (>350 lines or >128 KiB) and points agents at bulk_read.
Repo-level MCP registration helper:
python3 -m mcp_portal.install plan
python3 -m mcp_portal.install apply --target claude-mcpSecurity
See SECURITY.md. Summary: you choose which files leave the machine; the CLI runs read-only with tools denied; quotes are verified server-side. Not a substitute for secret hygiene.
Related projects
Several Node-based bridges expose Cursor via MCP (different tradeoffs: SDK/Node stack, varying isolation and verification):
mcp-portal focuses on stdlib Python, hash-pinned manifests, quote verification, server-side writes for code_write, model policy, and WSL-first Windows support.
License
MIT — see LICENSE.
Available Tools
3 toolsbulk_readC
Read authorized files and answer a question via Cursor CLI (read-only).
Inputs: paths (required), question (required), root, model.
code_writeC
Generate code from a spec and reference file; optional server-side write.
Inputs: spec (required), reference_path (required), model, target_path.
statusB
Cursor CLI path, auth, cache location, and receipt counters.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool serves a clearly distinct purpose: bulk_read is read-only Q&A, code_write generates and optionally writes code, and status reports configuration. There is no overlap in functionality that would cause misselection.
bulk_read and code_write use snake_case but with different modifier patterns (bulk_read is modifier+verb, code_write is noun+verb), while status is a bare noun. The mix makes the convention only partially predictable.
Three tools is within the typical 3-15 range and each earns its place for a focused portal. However, the surface feels slightly thin for a server handling both file reading and code generation.
The domain appears to be Cursor CLI operations for reading and writing code. Core create and read operations exist, but update, delete, and list operations are missing, leaving notable gaps for a full lifecycle.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Use your own Windows, Mac or Linux computer from ChatGPT, Claude, Cursor or Gemini CLI: run commands, read, write and search files, run long processes. Your computer only makes an outgoing connection (no open ports or VPN). Read-only mode, allowed folders, blocked commands and an action log keep you in control. Free plan available.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server wrapping the Cursor CLI agent, enabling Claude Code and other MCP clients to delegate tasks to Cursor's AI agent for file writing, bash commands, and codebase queries.-
- AlicenseAqualityBmaintenanceMCP server that lets any agent or MCP host delegate tasks to the Cursor CLI agent for fast, headless execution. Supports task delegation, project discovery, file analysis, and follow-up sessions.35MIT
- AlicenseBqualityDmaintenanceA fast, hardened MCP server that lets any MCP host drive the Cursor Agent CLI for heavy repo-aware tasks like search, analysis, planning, and edits, keeping host context small and token costs low.101MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that lets Claude Code or any MCP client delegate coding tasks to the local Cursor Agent CLI, with persistent per-workspace sessions and tools for diffing and pushing changes.12 npmMIT