MateMCP

MateMCP

Your agent hit a limit? Keep working.

Website: matemcp.com · Account portal: api.matemcp.com · Releases: agent-latest

MateMCP helps you get more useful work from the AI plan you already pay for. When a provider's built-in coding or agent tool reaches its usage limit but the AI chat itself is still available, MateMCP gives that conversation a controlled path to your own Windows or macOS computer — so useful work can keep moving on your real projects and tools.

MateMCP does not increase or bypass a provider's usage quota. It gives compatible AI clients another way to work through MCP, using your machines and your access rules.

Bring your own AI. Connect ChatGPT, Claude, Grok, or another compatible MCP client to an enrolled MateMCP Agent. The Agent can work with project files, shells, browsers, desktop applications, attachments, secrets, and durable project context while MateMCP keeps access scoped, authenticated, observable, and approval-aware.

The public website at matemcp.com is the product and onboarding surface. The authenticated account portal at api.matemcp.com handles account access, enrolled devices, approvals, and administration. The normal desktop experience remains simple: install MateMCP Desktop, enroll the device, copy its MCP URL into your AI client, and authorize it with OAuth. You do not copy Agent credentials or expose local ports to the Internet.

Why MateMCP?

• Keep going when built-in agents stop — if the chat is still available, give it a controlled path to your own tools instead of ending the work session.
• Make more of the AI plan you already have — use capable chat time for real local work without requiring MateMCP to replace your AI provider.
• Bring your own AI — use ChatGPT, Claude, Grok, or another compatible MCP client with the same local Agent model.
• Work on real machines — files, shells, browsers, desktop apps, attachments, and project context live where your work already lives.
• Stay in control — project scopes, OAuth, approvals, auditability, and local secret handling keep powerful access explicit.

What can MateMCP do?

• Project-scoped filesystem access — read and modify files only inside configured projects.
• Shell and interactive terminal sessions — run commands, keep long-lived shells, resume output after transient reconnects, and inject approved secrets without revealing them to the AI.
• Computer Use — inspect screenshots, interact with browser/native UI, click, type, scroll, and use semantic accessibility actions where supported.
• Browser automation and visual QA — navigate applications, inspect responsive layouts, capture screenshots, and support frontend/desktop verification workflows.
• Secure attachment transfer — upload conversation files to a selected Agent using bounded, resumable, integrity-checked transfers.
• Approvals — require local or remote approval for sensitive actions and keep decisions auditable.
• Secret Manager — keep user-managed credentials in the operating system credential store instead of model context or project files.
• Activity, audit, and diagnostics — see what the Agent is doing, inspect approval/credential activity, and diagnose connectivity or execution failures.
• Skills & Memory — keep global cross-project knowledge in the Agent, while project-specific knowledge lives as versioned repository SKILL.md files and travels with Git.
• Multi-device access — enroll multiple independently revocable Agents under one account.
• Resilient connectivity — logical sessions survive short Agent/Relay disconnects, operations use stable identities, and supported streams/transfers can resume safely.

How it fits together

flowchart LR

User[User / Admin] Site[Public website\nmatemcp.com] Portal[Account portal\napi.matemcp.com] AI[AI client\nChatGPT / Claude / Grok / MCP client] Relay[MateMCP Relay] API[OAuth Control Plane] Agent[Local MateMCP Agent] Companion[Companion] Machine[Projects · Shell · Browser · Desktop · Secrets]

User --> Site User --> Portal Portal -->|account / devices / approvals / admin| API AI -->|OAuth + MCP| Relay AI -->|Authorize| API Relay <-->|resilient Agent channel| Agent Agent --> Machine Companion <-->|local management| Agent Companion -->|approvals / status / logs| Machine Relay -->|authorization checks| API

The public website explains the product and provides onboarding entry points. The account portal is the browser-based user/admin surface for accounts, devices, approvals, and administration. The Relay carries remote MCP traffic to the correct online Agent. The Control Plane handles accounts, Agent ownership, OAuth, authorization, and remote approval coordination. The Agent performs work locally. The Companion gives the user a native view of status, approvals, shells, secrets, activity, diagnostics, updates, and Agent lifecycle controls.

Trust and security model

MateMCP is designed to be a boundary between an AI and the user's computer, not a tunnel around local security.

• Every Agent has a random public ID and a separate high-entropy private credential.
• Agent credentials and user-managed secrets are stored in macOS Keychain or Windows Credential Manager.
• The MCP URL identifies an Agent; it is not itself the Agent's secret credential.
• OAuth tokens are bound to the user, Agent/resource, and granted scopes. Access tokens can be refreshed without repeatedly asking the user to reconnect.
• Filesystem access stays inside configured project roots.
• mcp:read, mcp:write, and mcp:shell capabilities are enforced rather than inferred from the URL.
• Sensitive actions can require explicit approval; approvals and credential use are auditable.
• The Relay never needs the user's OS secrets.
• Attachment transfers are approved, bounded, resumable, and optionally SHA-256 verified.
• Agent and Relay reconnects use stable session/operation identities to reduce duplicate side effects after transient failures.

See docs/security.md and docs/approval.md for the detailed model.

Quick start

1. Create or sign in to your MateMCP account at [api.matemcp.com](https://api.matemcp.com).
2. Install MateMCP Desktop for your computer using one of the commands below.
3. Open Companion and finish device enrollment if prompted.
4. Copy the Agent's unique MCP URL, for example https://relay.matemcp.com/mcp/agt_....
5. Add that URL to ChatGPT, Claude, Grok, or another MCP-capable AI client.
6. Complete OAuth with the same MateMCP account that owns the Agent.
7. Try a safe first task, such as asking the AI to list a configured project or inspect a file.
8. Review approvals in Companion or the account portal when a sensitive operation requires consent.

After an Agent update that adds or changes MCP tools: some clients can retain a previous tool snapshot. For ChatGPT, see ChatGPT MCP tool refresh after Agent updates.

Install / upgrade MateMCP Desktop

macOS

For Apple Silicon Macs:

curl -fsSL https://raw.githubusercontent.com/vrassouli/MateMCP/main/scripts/bootstrap-macos.sh | bash

The bootstrap installs or upgrades Agent + Companion in place, starts the Agent, opens Companion for interactive setup when needed, and preserves existing configuration and secure credentials.

Manual package: MateMCP Desktop for macOS Apple Silicon · latest stable release

The Agent runs as a per-user LaunchAgent. Companion is installed under ~/Applications/MateMCP Agent Companion.app. Private configuration lives under ~/Library/Application Support/MateMCP; credentials and secrets use macOS Keychain.

Computer Use requires the relevant macOS Accessibility and Screen Recording permissions. Production signing/TCC identity hardening is still being improved, so development/ad-hoc builds may require permissions to be granted again after some updates.

Windows

Run from PowerShell:

irm https://raw.githubusercontent.com/vrassouli/MateMCP/main/scripts/bootstrap-windows.ps1 | iex

On Windows x64 the bootstrap installs or upgrades Agent + Companion, starts the background Agent, opens Companion when interactive setup is needed, and preserves the user-scoped configuration and credentials.

Manual package: MateMCP Desktop for Windows x64 · latest stable release

Private configuration lives under %APPDATA%\MateMCP; enrolled credentials and secrets use Windows Credential Manager.

Platform status

Remote MCP client status

Public Relay reachability can depend on the network path used by the client provider. The production MateMCP deployment can use Cloudflare or another HTTPS edge/reverse proxy in front of the public hostnames without changing the Agent-facing MCP URL model.

Companion at a glance

Companion is the user's local control surface. Current functionality includes:

• Agent Start / Stop / Restart and status.
• MCP endpoint visibility and copy actions.
• Pending Approvals and policy management.
• Interactive Shell sessions.
• Secret Manager backed by the OS credential store.
• Activity & Audit history.
• Agent Logs and diagnostics.
• Global Skills & Memory inspection and management; project Skills are ordinary versioned files inside each repository.
• Computer Use preview/status.
• Prevent Sleep While Using controls, with a 15-minute idle grace period after the latest Agent activity.
• Manual update checks and optional automatic Desktop updates on supported platforms.

Account portal at a glance

The browser-based account portal at [api.matemcp.com](https://api.matemcp.com) complements the local Companion. Current portal capabilities include:

• Login and registration with normal account/session controls.
• Device management for enrolled devices, including status and revoke/remove flows supported by the control plane.
• Approvals with pending actions and recent/history views supported by the backend.
• Administration for authorized admins, including user search/status management and appropriate device management.
• Server-side authorization for user/admin actions; sensitive Agent credentials and stored secrets are not exposed through the portal.

Self-