MateMCP README

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.
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 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-host Web + Account Portal/API + Relay

For the usual single-server deployment there is one canonical install/update command:

curl -fsSL https://raw.githubusercontent.com/vrassouli/MateMCP/main/deploy/install.sh | sudo bash

The installer is update-safe: it preserves existing configuration, asks only for missing setup values, refreshes the current Compose definitions, pulls/recreates the public Web, API, and Relay services, keeps the private API↔Relay credential synchronized, and health-checks the services before reporting success. On supported Debian/Ubuntu hosts it can bootstrap Docker Engine + Compose when needed.

Use component installers only for advanced deployments where Web, API, and Relay are managed separately:

# Public product website
curl -fsSL https://raw.githubusercontent.com/vrassouli/MateMCP/main/deploy/web/install.sh | sudo bash

# API / Control Plane
curl -fsSL https://raw.githubusercontent.com/vrassouli/MateMCP/main/deploy/api/install.sh | sudo bash

# Relay
curl -fsSL https://raw.githubusercontent.com/vrassouli/MateMCP/main/deploy/relay/install.sh | sudo bash

The API supports SQLite for a small single-server deployment and SQL Server for external database deployments. Web, API, and Relay should sit behind HTTPS reverse proxies; their container ports should not be exposed directly to the Internet. Keep matemcp.com, api.matemcp.com, and relay.matemcp.com routed to their independent backends.

External identity providers are optional and deployment-specific. Provider configuration, callback URLs, and account-linking behavior are documented in docs/external-login-providers.md; enable only providers that have been configured and verified for the deployment.

Cloudflare is optional. When it is used in front of MateMCP, keep the three public hostnames independently routed, preserve the original HTTPS host/scheme, and do not cache authenticated API responses. The same deployment pattern also works with other HTTPS reverse proxies/edges.

Production hostname/TLS routing is documented in docs/production-web-deployment.md. Web deployment details are in deploy/web/README.md, and Relay-specific reverse-proxy guidance remains in deploy/relay/README.md.

Documentation

Current limitations and active work

MateMCP is under active development. Some areas intentionally remain conservative or are still being hardened:

• Native Companion packaging is currently focused on Windows x64 and macOS Apple Silicon.
• Windows ARM64 uses screenshot fallback rather than the native WGC preview helper.
• macOS production signing/TCC identity still needs hardening so permissions survive every production update reliably.
• Global Skills & Memory and repository Skills exist today, but proactive automatic context use across different AI clients is still evolving.
• ChatGPT remains the primary full end-to-end compatibility target; Claude and Grok connectivity has also been verified, while provider-specific feature behavior can still differ.
• Safe & Informed Approvals is being expanded so approval dialogs explain consequences and risk rather than relying only on raw command syntax.

Releases

main is the source of truth for stable development. The moving agent-latest release contains current stable Agent packages and native Desktop packages for supported architectures. Version tags such as v0.1.0 publish versioned release assets.

Contributions and field-test reports are welcome through GitHub Issues and Pull Requests.