Connect, authorize, and set up your agent.

Run locally without an account

The signed macOS download is not available yet. Clone the source repository and open its directory. Install Go 1.26 or newer and the prerequisites in its README.

1. Build with go build -o bin/mcpainless ./cmd/mcpainless, then run bin/mcpainless serve.
2. Open http://127.0.0.1:37193 and create a master password. Keep the app running for agent requests.
3. Add a catalog connector or a manual HTTP endpoint or stdio command. Authorize the provider, connect, and review its tools.

Local use needs no account, link, or trial. A local endpoint stops while the app is locked or closed.

Use Cloud

1. Create an alpha account with an invite code. Account creation does not start a trial.
2. Open Settings → Account and sync. Review and enable configuration sharing for Cloud. Enrolled configuration editing needs no active execution trial.
3. Confirm your 14-day trial before connecting or creating hosted agent access. Approve Cloud credential storage when authorizing a provider.

Cloud can store stdio and private-network configuration, but cannot execute it. Use a local deployment for those servers.

Cloud OAuth needs MCPainless running on the same computer as the browser for the loopback callback. The local app can stay locked.

Set up an agent

1. Open Clients and setup on the connector Overview. Select an existing installation or create a named installation and token.
2. For Codex or Claude Code on the local app, choose Preview setup. Review the target file and entry, accept the plaintext credential copy, then Apply changes.
3. In Cloud, download configuration instead. Cloud cannot write this computer’s files. Other recipes use manual, unverified connection details.

Agent files, downloads, and agent-managed backups can contain plaintext credentials. Keep them private. Rotation stops the old token; preview and apply setup again, or download its replacement.

The dedicated endpoint keeps its deployment-local slug. Gateway is an experiment that combines selected connectors at https://mcp.mcpainless.app/mcp. Gateway has separate access tokens.

Share settings explicitly

1. Use Settings → Account and sync to sign in and link a deployment. Linking does not share configurations or start a trial.
2. Review the URLs, commands, and working directories. Enable sharing separately on each deployment for all its existing and future configurations.
3. Review changes in Account and sync. Automatic sync runs while the local app is running and unlocked. Sync now makes one attempt even when automatic sync is paused.

Cloud can read shared settings, including URLs, commands, working directories, and environment variable names. Keep credentials in dedicated fields or local environment values.

Provider credentials, generated registrations, environment values, slugs, and agent tokens stay on their deployment. Imported commands need local approval. Sharing never activates execution.

Conflicts require an explicit version choice. Local disconnect retains local data and queues remote revocation if Cloud is unavailable. Retries continue while the app is running and unlocked.

Older encrypted sync needs explicit migration before this format can be shared. Old clients cannot write after migration.

Resolve authorization problems

Use Automatic sign-in for provider registration, optionally with an HTTPS client metadata document URL. Use OAuth credentials for a supplied client ID and optional secret. Bearer tokens stay in their dedicated field.

For Cloud OAuth, register the exact loopback callback displayed by the form and keep the local app running on this browser’s computer. A provider that rejects that callback is unsupported for this Cloud flow.

Use Test authentication for a saved grant. An uncertain refresh requires Authorize again. MCPainless does not replay an ambiguous refresh request.

Denied consent or discovery failure before token exchange preserves a previous working grant. A valid replacement token exchange commits the new grant, even if later tool discovery fails.

Catalog entries retain their selected version. Unknown provider support is unverified; fixture tests do not prove a live provider authorization.

Understand activity retention

Raw tool-call activity expires after 30 days. Usage totals remain when those records expire. Tool counts, errors, average duration, and last use continue to update.

Previously deleted history cannot be recovered. Rediscovering the same tool retains its totals. Permanent connector removal deletes its totals.