You already have an MCP server for GitHub, Sentry, Google Search Console, or another service. Miftah helps when that same server needs to work across more than one account, client, project, or environment.
Miftah runs locally in front of the upstream MCP server. You configure one Miftah connector for a service, give its accounts names such as work, personal, or production, and select the profile you intend to use.
Claude, Cursor, or VS Code
│
one Miftah connector
│
┌────┴────┐
work personal
│ │
same upstream MCP
Miftah itself has no cloud service or telemetry. It adds local profile selection, credential references, policy, approvals, redaction, diagnostics, and optional audit metadata around an upstream; it does not replace that upstream or widen what the upstream supports.
Status: Miftah is experimental and pre-1.0. Interfaces and security behavior may change between minor versions. External multi-account and returning-user validation in #25 and #88 remains open.
Already using Miftah? See What is in 0.5 and how to use it for the release's guided setup, profile-management, Console, OAuth, and upgrade paths.
Use Miftah when:
- the same MCP service needs separate work, personal, client, or environment accounts;
- you want the account choice to be visible and deliberate;
- credentials should stay out of MCP client configuration;
- local policy, approvals, redacted diagnostics, or audit metadata would help.
Keep your direct MCP entry when you use one account and do not need those controls. Miftah is a wrapper, not a universal compatibility layer: the upstream server still owns its provider tools, runtime requirements, and provider-specific behavior.
Without Miftah, two GitHub accounts often become two almost-identical client entries such as github-work and github-personal. With Miftah, the client has one github connector and the accounts live behind it as named profiles.
| Duplicate client entries | One Miftah connector |
|---|---|
| Copy launch settings for every account | Keep launch settings in one reviewed configuration |
| Put account wiring in the client file | Keep profile-scoped credential references outside the client |
| Choose an account by choosing a server entry | List, inspect, and deliberately switch named profiles |
Miftah exposes management tools such as miftah_list_profiles, miftah_current_profile, and miftah_use_profile. Advanced connection-scoped profile locking uses miftah_lock_profile and miftah_unlock_profile only when explicitly enabled. The upstream's tools keep their original names.
Install Miftah, then choose the terminal wizard or the browser Console. Both use the same validated setup services. The terminal wizard can start from a known connector, remote HTTPS MCP, reviewed local executable, supported browser sign-in, or one existing client entry. The browser Console provides first-run setup for a known connector or a standards-compatible remote MCP with native OAuth.
npm install -g @lubab/miftah@0.5.5
miftah versionTerminal wizard
miftah setupThe wizard shows numbered choices, lets you go back before entering connection details, validates before writing, and can print client JSON for manual review.
Browser Console
miftah dashboardKeep the foreground terminal open, enter its one-time code in the local browser page, then choose Set up an MCP. miftah dashboard is the browser UI; the similarly named miftah console command starts the lower-level local control API.
Neither path asks for a token, password, or browser cookie. Miftah does not silently edit Claude Desktop, Claude Code, Cursor, or VS Code settings.
Follow the generated handoff to review one client connector, merge it into your client settings, and restart or reconnect that client.
Use miftah init when you want a repeatable preset command instead of either human-first flow. This example creates one Claude Desktop connector with work and personal GitHub profiles. It requires Docker.
miftah init github --preset github --output ~/.config/miftah/github.json --client claude-desktopMiftah creates ~/.config/miftah/github.json and prints a Claude Desktop mcpServers snippet. It does not edit Claude Desktop and does not ask for or write a token.
The generated profiles refer to GITHUB_WORK_TOKEN and GITHUB_PERSONAL_TOKEN. Provide least-privilege tokens through a supported secret provider, not as raw values in the Miftah or Claude JSON. OS keychain references use secretref:keychain://; 1Password references use secretref:op://. Claude Desktop is a GUI app and does not normally inherit variables from terminal startup files such as ~/.zshrc.
After those credential references are available to the process that will launch Miftah, run:
miftah validate --config ~/.config/miftah/github.json
miftah doctor --config ~/.config/miftah/github.json
miftah test-profile --config ~/.config/miftah/github.json --profile workvalidate checks configuration shape. doctor checks redacted credential and upstream readiness. test-profile starts and initializes only the selected profile. None proves provider scopes or account identity beyond the evidence it actually reports.
Merge the printed mcpServers entry into Claude Desktop through Developer → Edit Config, save, and restart Claude Desktop. Then ask:
List the profiles available through `github`.
Switch `github` to the personal profile.
Confirm the current profile before reading my repositories.
The generated GitHub policy requires confirmation for a profile switch. See the complete GitHub walkthrough and Claude Desktop setup for credential and client details.
If readiness fails, rerun the exact diagnostic command for this file:
miftah doctor --config ~/.config/miftah/github.jsonThen use Troubleshooting.
Start from what the upstream MCP server already uses:
| What you have | Start here | Who owns authentication |
|---|---|---|
| API key, token, or another secret | Run miftah setup, or use a reviewed preset from Preset and client compatibility. Store only a secret reference. |
The upstream/provider owns the credential; Miftah resolves the configured reference for one profile. |
| Standards-compatible remote HTTPS MCP with OAuth | Use miftah setup --native-oauth and OAuth support. |
Miftah owns only its supported discovered browser flow, OS-vault credential, refresh, reauth, and local disconnect. |
| Local or provider-specific MCP that opens its own login | Use the upstream or a reviewed adapter such as Google Search Console. | The upstream owns browser login, token cache, refresh, reauth, and revocation. Miftah does not scrape that cache. |
| One existing MCP client entry | Run the guided miftah setup import path. |
Miftah imports only a supported non-secret launch shape; it does not infer OAuth ownership or modify the source client file. |
| Reviewed local executable or exact-pinned package/container | Use local-stdio, generic-npx, or generic-docker from Setup paths. |
The upstream owns authentication; Miftah launches with literal argument arrays and no shell. |
Native OAuth is intentionally narrow and is not promised for every remote MCP or provider. A successful login, resolvable secret, or profile label is not proof that the credential has the intended scopes or belongs to the intended account. Use a configured identity probe when the upstream offers stable bounded identity evidence.
On Windows, generic, sentry, and generic-npx are unavailable. Miftah refuses them instead of invoking cmd.exe. Use a reviewed direct .exe or .com executable, a direct-executable adapter such as Docker or uvx.exe, or a remote MCP. The compatibility matrix records the exact platform limits.
miftah setupis the guided terminal wizard. It asks what you already have, collects only the metadata needed for that path, validates before writing, and never asks for a token, password, or browser cookie.miftah initis the optional scripted preset path shown in the quick start.miftah dashboardopens the optional foreground-only local Console for reviewed setup, profiles, health, and OAuth lifecycle work. It is not required to run Miftah.- Client generation can print reviewable snippets for Claude Desktop, Claude Code, Cursor, and VS Code. Miftah never silently edits their settings.
See Setup paths for exact presets, client destinations, generated JSON shapes, upstream requirements, and platform support. See the Console guide for its local authenticated control boundary.
- Keep raw secrets, OAuth credentials, provider caches, dotenv files, active-profile state, audit journals, and generated machine-local client JSON out of shared configuration. Reviewed profile names, policy, routing, upstream metadata, and secret references may be shared only when no plaintext secret is present.
- Local policy can allow, deny, or require confirmation, but it cannot reduce permissions already granted to a provider credential.
- Identity verification is optional and upstream-specific. Credential readiness, token health, and verified account identity are different claims.
- Audit records are redacted local metadata. Optional hash chaining provides local tamper evidence, not a remotely anchored immutable trail.
- Remote OAuth, local/provider-owned OAuth, and static secret references have different owners and lifecycle behavior; choose the matching setup path above.
Read the Security boundary and threat model before deploying Miftah in a sensitive environment.
- Setup paths — presets, supported clients, pins, platform limits, and generated snippets
- Configuration reference — profiles, secrets, routing, policy, identity, and audit configuration
- OAuth guide — native remote OAuth and upstream-owned OAuth
- CLI reference — commands, diagnostics, exit codes, logs, and Troubleshooting
- Console guide — optional local dashboard and API
- Security boundary, Threat model, OAuth and Console security design, and Architecture
- profile credential isolation, routing context, and provider routing matchers
- Provider adapters, plugins, and library API
For bugs and feature requests, open an issue. Report vulnerabilities through the private process in SECURITY.md.
MIT. See LICENSE.