mcp-agentic-server

Agentic MCP — Local Coding Tools for ChatGPT Developer Mode

Connect compatible ChatGPT Web accounts to local coding tools through MCP Developer Mode.

Agentic MCP connects ChatGPT Web Developer Mode to your local repositories through a secure Model Context Protocol (MCP) server. It supports structured file editing, shell execution, Git worktrees, semantic navigation and checkpoints.

ChatGPT Web → Developer Mode → HTTPS Tunnel → Agentic MCP → Local Repository

[!WARNING] Security Notice: This tool runs on your local machine and can execute shell commands. A managed Git worktree provides an isolated Git checkout to prevent polluting your main repository, but it is not an operating system sandbox. It does not restrict network access or subprocesses. Always review what the LLM intends to run.

[!NOTE] Disclaimer: Agentic MCP is an independent open-source project and is not affiliated with, sponsored by, or endorsed by OpenAI. ChatGPT and OpenAI are trademarks of OpenAI. Tested by the maintainer with ChatGPT Plus using Developer Mode and an HTTPS tunnel. Availability of MCP capabilities depends on the user's ChatGPT plan, workspace configuration and current OpenAI rollout.

🌐 Official MCP Registry

Agentic MCP is published in the Official MCP Registry as: io.github.hugolsramos01-bit/mcp-agentic-server

Install and run locally for Claude Desktop, Cursor, or other local MCP clients:

npx -y mcp-agentic-server@latest stdio

⚡ Quickstart: ChatGPT Plus Setup in 3 Minutes

Turn ChatGPT Web into your primary local coding agent using your existing Web plan:

• Initialize and start the server:

  npx -y mcp-agentic-server@latest init
  npx -y mcp-agentic-server@latest serve
  

• Expose the local port (7676) via an HTTPS tunnel:

  ngrok http 7676
  

• Enable Developer Mode in ChatGPT Web:

  • Go to chatgpt.com > Settings > Apps / Developer Mode (or Plugins / Apps).
  • Enable Developer Mode.

• Connect the Custom MCP App:

  • Add a new Custom MCP App.
  • Enter your public ngrok HTTPS URL ending with /mcp:

    https://YOUR-SUBDOMAIN.ngrok.app/mcp
    

• Complete OAuth Authentication:

  • Complete the local browser OAuth authorization prompt when presented.

• Start Coding:

  • In a new ChatGPT Web chat, enable your custom MCP app and prompt:

    "Open workspace C:/path/to/project using open_workspace and summarize the architecture."

🙋 Frequently Asked Questions (FAQ)

Does this work with ChatGPT Plus?

Tested by the maintainer with ChatGPT Plus via Developer Mode and a public HTTPS tunnel (ngrok, Cloudflare Tunnel, etc.). Availability may vary by account, region, plan, and rollout.

How does this affect my limits and billing?

When connected directly through ChatGPT Developer Mode, model usage is handled by the user's ChatGPT account rather than by an OpenAI Platform API key. Applicable limits depend on the user's plan and OpenAI policies.

Does it require an OpenAI API key?

No OpenAI model API key is required. Authentication for the MCP server and tunnel is separate from model API billing.

Is this an alternative to Codex or Claude Code?

Yes. It gives ChatGPT Web full local coding capabilities: file inspection, structured line-precise editing, shell execution, Git worktrees, AST navigation, and checkpoints.

🚀 Release 1.8.0 Highlights

Version 1.8.0 turns read_many into a bounded composite inspection primitive instead of merely a multi-file reader:

• One round trip, several related inspections — ordered items can mix exact reads/ranges, scoped lexical matches with context, and scoped globs.
• Shared output budgets — approximate serialized-evidence, returned-line, and unique-file limits apply across the whole call; earlier items have explicit priority, glob results return the useful subset that still fits, and the response reports estimated final payload overhead separately.
• Context de-duplication — overlapping match windows in the same file are merged before they reach the model.
• Progressive narrowing — broad discovery is reserved for genuinely unknown architecture; once a target area is known, agents are directed toward a bounded composite inspection instead of restarting broad context collection.
• Cross-platform bounded discovery — Git-aware file listing respects ignored files even for empty scoped results, with a bounded non-Git fallback and explicit scan-truncation metadata. Match items can also filter files with include globs.
• Bounded regex opt-in — literal search remains the default; explicit regex mode rejects several high-risk backtracking constructs, limits scanned bytes, and skips abnormally long lines instead of letting one search monopolize the server.
• Fail-closed resource bounds — incompatible operation fields are rejected instead of ignored, legacy paths calls remain supported, and composite reads cap path/file/source-byte loading plus diagnostic string sizes so a narrow request cannot accidentally create an oversized filesystem or response payload.

🚀 Release 1.6.0 Highlights

Version 1.6.0 focuses on lower-latency coding loops without weakening the security and verification boundaries introduced in 1.5.0:

• Three command security modes — safe remains the default, trusted enables practical inline scripting and shell file writes while retaining destructive-command protections, and full is available for explicitly unrestricted local execution.
• Proportional coding workflow — QUICK, STANDARD and CRITICAL changes no longer pay the same PVDL and verification cost; strict PVDL remains an explicit override for environments that require it.
• Stop-discovery discipline — known files and symbols are inspected directly instead of triggering broad bootstrap/context exploration merely to reconfirm an already strong target.
• Bounded fast context — read_many defaults to 12k tokens, fast task context caps large code-region reads at 160-line anchor windows, and file indexes stay warm across normal model reasoning gaps.
• Faster QUICK review — with AGENTIC_WIDGETS=changes, single-file edit/write mutations carry their review UI directly and no longer need a redundant aggregate show_changes round trip.

🔥 Key Innovations

1. Smart Context Anti-Bloat

Stop melting your LLM context windows and preserve your ChatGPT Web message limits.

• workspace_summary: Instead of a massive unified file dump, returns a compact, high-level map of the workspace (git status, package manager, key scripts, and schemas).
• Hardened File Reads: The read tool forces offset/limit paginations and strict line-range constraints. The model gets exactly what it needs, down to the line, preventing catastrophic token bloat on large files.

2. True Git Worktree Sandboxing

Running experimental code, tests, or destructive LLM edits in your main directory can break your Hot Module Replacement (HMR), trigger infinite loops in Next.js/Vite, or mess up your node_modules.

• open_workspace (mode="worktree"): Automatically spins up an isolated, detached git worktree outside your project's main directory (e.g., ~/.agentic/worktrees/).
• The LLM can break things, install new dependencies via worktree_install_deps (with allowLifecycleScripts safely controlled), or sync uncommitted changes via worktree_sync_changes, all without touching your live development environment.

3. Semantic AST Navigation

The server parses TypeScript and JavaScript dynamically (with an in-memory LRU cache to save CPU) to provide the model with semantic maps of your architecture.

• next_route_map: Maps out Next.js App Router and Pages Router dynamically, showing roles (api, page, layout) and dynamic segments.
• payload_schema_map: Analyzes Payload CMS collections to return a clean map of fields, hooks, and relationships.
• file_dependencies: Maps outward (what a file imports) and inward (who imports the file) dependencies instantly.

4. Safe Editing & Dry-Runs

• edit_dry_run: Simulates replacements to validate exact string matching and uniqueness, returning the surrounding context of the would-be edit without saving to disk.
• changed_files_summary: Fast, accurate summaries of modified and newly staged files using git status --porcelain.

5. Checkpoint System

For long autonomous sessions, the agent can save point-in-time snapshots of the workspace (checkpoint_save), list them (checkpoint_list), and roll back (checkpoint_restore) if it goes down a bad architectural path.

💻 Local & Desktop MCP Clients (Claude Desktop, Cursor, Roo Code)

If you prefer using desktop MCP hosts, configure your client configuration file to use the stdio transport:

{
  "mcpServers": {
    "agentic-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-agentic-server@latest", "stdio"],
      "env": {
        "AGENTIC_ALLOWED_ROOTS": "C:/path/to/projects"
      }
    }
  }
}

🛠 Available Tools Reference

The tool surface depends on the AGENTIC_TOOL_MODE setting.

Mode	Tools included	Use case
assistant (default)	Canonical coding workflow: workspace, context, read/search, Git, checkpoints, edit/dry-run, package scripts, worktrees, diagnostics, and semantic maps.	Full coding-agent workflow with curated model instructions.
full	Base tools + grep, glob, ls	Manual inspection via shell
minimal	open_workspace, read, write, edit, bash	Restricted surface

Note: The assistant mode is recommended for the full agentic coding experience. Set AGENTIC_TOOL_MODE=assistant in your .env or environment.

Command security modes

Tool mode and command security are separate. AGENTIC_SECURITY_MODE controls what shell commands may pass the policy engine:

Security mode	Behavior
safe (default)	Strict command policy. Blocks inline scripting/file-writing shell constructs and destructive commands.
trusted	Allows python -c, node -e, redirects, heredocs and in-place shell writes, while destructive operations remain protected.
full	Bypasses command-policy restrictions, including destructive-command rules.

Persist the setting with agentic config set securityMode safe|trusted|full, then restart the server. OAuth remains required. The shell is not an OS sandbox and may access anything available to the local user account, so trusted and especially full should only be enabled intentionally.

Core tools (always available)

Tool	Description
open_workspace	Opens a project. Supports mode="checkout" or mode="worktree".
read	Hardened file reader with startLine, endLine, offset, limit.
write	Create or overwrite files.
edit	Targeted string replacements.
bash	Fallback for shell interactions that have no typed tool; prefer run_package_script for package scripts and the Git tools for Git.
visual_review	Capture a local web app at responsive desktop/laptop/tablet/mobile viewports and return PNG screenshots directly to the model. Supports custom viewports; local URLs only.

Assistant tools (mode: assistant)

Tool	Description
workspace_summary	Compact architectural summary of the workspace.
project_bootstrap	Scans package managers, monorepo bounds, and base dependencies.
read_many	Composite bounded inspection: exact reads/ranges, scoped match+context (with optional file include glob), and scoped globs in one ordered call with shared serialized-evidence/line/file budgets and payload-cost reporting.
tree	Directory tree visualization.
next_route_map / payload_schema_map	Next.js / Payload CMS schema extraction.
file_dependencies	Inward and outward dependency map.
checkpoint_*	Save, restore, list, or delete snapshots.
edit_dry_run	Preview edits without writing.
worktree_*	Manage isolated git worktrees (create, list, sync, teardown).
worktree_install_deps	Install dependencies in a managed worktree; use verify: true to load native bindings.
agentic_doctor	Diagnose Node, package managers, Git and native SQLite availability.
semantic_pack	Compact goal-relevant summary with token budget.
context_budget	Estimate token count for files.
expand_compressed_block	Expand omitted blocks from read_compressed.
token_audit	Analyze token usage across files read.
tournament_*	Autonomous evaluation and judgment of changes.
risk_assess_command	Preview policy assessment before bash.
changed_files_summary	Fast Git status and diff abstraction.
task_context	Computes a RiskProfile (risk level, score, blast radius) from focused paths.
suggest_checks	Advisory planner returning a deterministic VerificationPlan.

Verification & Risk (Expanded in 1.5.0)

The risk and verification pipeline enforces strict, deterministic planning.

• task_context now produces a RiskProfile accounting for sensitive configuration, fan-out, test proximity, and analysis confidence.
• suggest_checks returns a VerificationPlan and is advisory only (commands are not executed). Mutating checks and non-existent scripts are excluded. Low confidence can elevate policyLevel without altering the intrinsic riskLevel. When local Git metadata is unavailable, the planner uses goal_discovery from the stated goal and focused paths instead of inheriting an ancestor repository.

Supported Inputs:

{
  workspaceId: string;
  changedPaths?: string[]; // Actual paths changed
  goal?: string;           // Optional goal for discovery
  taskType?: "auto" | "bug_fix" | "feature" | "refactor" | "security_review" | "migration" | "frontend" | "release";
  focusPaths?: string[];   // Specific files to focus on

  // Legacy compatibility transition (deprecated)
  paths?: string[];
  scope?: "changed" | "workspace";
  level?: "minimal" | "recommended" | "full";
}

Deprecated compatibility aliases are hidden by default and never appear in the model's standard workflow. Existing clients can temporarily opt in with AGENTIC_LEGACY_ALIASES=1; they will be removed in the next major release. New clients must use the canonical names above: edit_dry_run, next_route_map, payload_schema_map, changed_files_summary, and project_bootstrap.

🧠 Mental Model for Agents

This server is designed to act as the "hands and eyes" of a remote AGI. If you are building an autonomous agent or using Claude/ChatGPT for coding, instruct your agent to:

• Narrow progressively. If the relevant files are unknown, use task_context; if a strong target is already known, skip broad discovery.
• Use read_many to batch related exact reads, match+context inspections, and scoped globs in one round trip. Put the most important items first because item order is budget priority.
• Use semantic_pack only when broad domain structure or inter-file relationships are genuinely unknown; stop broad discovery once implementation targets are strong enough.
• Use read_compressed for large whole-file orientation — expand omitted blocks before editing them.
• Use mode="worktree" if the task involves running complex shell commands or destructive tests, and use edit_dry_run before ambiguous or risky replacements.

Isolation boundaries

A managed worktree is an isolated Git checkout, not an operating-system sandbox. It keeps experiments out of the primary checkout, but it does not restrict network access, subprocesses, credentials, CPU/memory use, or paths that are otherwise allowed to the server. Treat scripts as real local commands and use the typed Git/script tools first. Git tools only operate when the opened workspace itself is the repository root; an ancestor repository is rejected rather than exposing sibling projects.

📝 License & Acknowledgements

Licensed under the MIT License. See LICENSE for more details.

This project uses components heavily inspired by internal security architectures, with thanks to standard best practices in the open source community.

We welcome contributions! Please see CONTRIBUTING.md for details on how to get started.