Miftah MCP server
Commit Nov 11, 2026Acts as a local credential broker to manage multiple accounts and profiles for a single MCP server.
Also known as mohanagy/miftah
- Stars
- 5
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 11, 2026
- License
- MIT
What is Miftah MCP?
Miftah acts as a local credential broker to manage multiple accounts and profiles for a single MCP server.
Summary generated from the project's README
About Miftah MCP server
Managing multiple accounts for the same service from inside an AI client is what Miftah enables. Developers using Claude, Cursor, or VS Code can use a single connector for services like GitHub or Sentry while switching between distinct profiles such as work, personal, or production. This local broker sits in front of your existing MCP servers to provide organized account selection without requiring duplicate client entries for every environment.
Setup is handled through a terminal wizard or a local browser dashboard. You can configure connections using various methods, including remote HTTPS MCP with native OAuth, local executables, or Docker containers. Instead of placing raw tokens in your client configuration, Miftah uses secret references for tools like 1Password or the OS keychain. This approach keeps credentials out of your main client files and allows for local policies, such as requiring manual approval before switching profiles.
Management is performed through specific tools like miftah_list_profiles and miftah_use_profile. You can also use miftah_lock_profile to ensure a specific account remains active for a workspace. The system focuses on local control, offering redacted diagnostics and audit metadata to help you maintain visibility over which account your AI agent is currently using.
What you can do with it
- 1Switch between GitHub accountsTell your AI client to change from your work profile to your personal profile using a single GitHub connector.
- 2Secure credential managementKeep sensitive API tokens out of your Claude or Cursor configuration files by using secret references.
- 3Enforce account switching policiesRequire a manual confirmation step before the AI agent is allowed to switch to a different service account.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablemohanagy/miftah is public and reachablegithub.com/mohanagy/miftah ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/mohanagy/miftah ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMiftah
Use the right account with the MCP servers you already trust
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 1.0 is the stable v1 release line. Documented public compatibility surfaces follow Semantic Versioning. The external workflow and security-review gates were closed by maintainer attestation in #39; the source participant records and completed security report are not published in this repository.
Upgrading from Miftah 0.5? See What is in 0.5 and how to use it for the guided setup, profile-management, Console, OAuth, and upgrade paths introduced before the stable line.
Is Miftah for you?
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.
One connector, named profiles
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.
Quick start
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.
1. Install the current release
npm install -g @lubab/miftah@1.1.6
miftah version
2. Choose a human-first setup
Terminal wizard
miftah setup
The 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 dashboard
Keep 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.
Optional: scripted GitHub example
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 --active-profile-lifetime workspace --output ~/.config/miftah/github.json --client claude-desktop
Miftah 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.
--active-profile-lifetime workspace makes a successful live profile switch durable for this configuration, so a fresh Miftah process restores it. Choose process instead when every fresh process should return to the configured default profile. The terminal wizard and Console present this choice during multi-profile setup. Existing configurations without state keep temporary process behavior; miftah_current_profile, miftah_use_profile, and miftah_reset_profile report the effective scope and restart consequence.
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.
Validate before connecting the client
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 work
validate 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.
Connect and select the account
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.json
Then use Troubleshooting.
Choose your setup and authentication path
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.
Wizard, CLI, clients, and optional Console
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.
- Runtime protocol claims are narrower than snippet support; see the tested MCP protocol and client matrix for exact eras, transports, versions, and limitations.
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.
Safety boundaries
- 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.
Go deeper
- 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
- v1 external evaluation — privacy-safe workflows, unaided first-use checks, and returning-user evidence
- independent security review brief — review scope, deliverables, disclosure, and closure gates
- 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.
License
MIT. See LICENSE.
Miftah MCP questions
What does Miftah do?
Miftah runs locally in front of an upstream MCP server to help manage multiple accounts, clients, projects, or environments through named profiles.
Does Miftah store my passwords or tokens?
No, Miftah does not ask for or write tokens, passwords, or browser cookies, and it does not silently edit client settings.
Can I use Miftah with GitHub?
Yes, Miftah supports GitHub and can create a single connector with multiple profiles like 'work' and 'personal'.
Is Miftah a cloud service?
No, Miftah has no cloud service or telemetry and runs entirely locally.