Maza

Maza is a local MCP gateway. Connect your MCP servers once, then point Claude Code or another MCP client at Maza. Agents see two tools: find_tool discovers a capability through Jev Choice, and execute_tool runs it after the agent supplies arguments from the original schema.

The gateway manages connections, credentials, discovery, per-tool access and execution. It runs as a native Node.js process; Docker is not required. Jev is the gateway's only model integration. Planning and argument generation remain with the calling agent.

Requirements

• Node.js 22.13 or later and npm.

• An available OS credential store supported by @napi-rs/keyring. macOS Keychain has been tested. Linux/Windows credential-store integration has not been verified.

• A Jev API key from TypeSafe AI.

• Claude Code installed if you want automatic Claude registration.

• Each downstream MCP server's runtime and credentials, when required.

Related MCP server: mcpstead

Install and start locally

git clone https://github.com/prasanth263/maza.git
cd maza
npm ci
npm link
maza init
maza secret set jev
maza start

npm link makes the maza command available locally on your machine. If you prefer not to link it, replace maza with node /absolute/path/to/maza/src/cli.js in the commands below, or use npm run maza -- <command> from this repository.

maza secret set jev prompts for the key with hidden input. Paste the key and press Enter. The value is stored in OS credentials, not in the repository, shell arguments or configuration file. To replace the key later, run the same command; no daemon restart is needed solely for a key change. Missing or placeholder keys do not trigger a mock routing fallback.

By default, state is stored in ~/.maza. To use another directory, set MAZA_HOME before running commands, or pass --home /absolute/path/to/state to every command, including client registration. Use one consistent directory: credential namespaces depend on its absolute path.

# Optional: use project-local state instead of ~/.maza.
export MAZA_HOME="$PWD/.maza"

The service listens at http://127.0.0.1:47321. Open the local dashboard. Obtain its administrator token with:

maza token admin

Paste that token into the dashboard's password field. The dashboard can manage connections, discover tools, enable tools, store credentials and inspect metadata-only activity.

Add MCP servers through the CLI

Local command / stdio

For example, connect the filesystem MCP server to one allowed directory:

mkdir -p "$HOME/maza-files"
maza add stdio files -- npx -y @modelcontextprotocol/server-filesystem "$HOME/maza-files"
maza discover files
maza tools files
maza enable files/read_text_file
maza enable files/list_directory

Everything after -- is the downstream executable and its arguments. You can use an absolute executable path instead of npx, for example a Node script, Python executable or Docker command. Local MCP commands run as your OS user; Maza is not an OS sandbox.

Remote Streamable HTTP

Replace the example URL with your provider's MCP endpoint:

maza add http service https://example.com/mcp
maza discover service
maza tools service
maza enable service/tool_name

Remote URLs must use HTTPS, except for local loopback HTTP. Put credentials in header references rather than URL userinfo or query parameters. Legacy SSE-only endpoints are not supported.

Discovery and enablement

New tools are disabled until explicitly enabled. Tool IDs are namespaced as server/tool_name to avoid collisions.

maza discover                  # Refresh all enabled connections.
maza tools files               # Inspect original definitions.
maza enable files/read_text_file
maza disable files/read_text_file
maza enable 'files/*'           # Enable all currently discovered tools on files.

A changed tool definition requires renewed enablement. Selections bind to the original schema version and expire after five minutes. The gateway validates execution arguments and checks client access before proxying the call.

Authentication: three separate credentials

The Jev key is not a gateway login token. Downstream credentials are not passed to calling agents or included in routing payloads. Task/context and enabled tool names/descriptions are sent to Jev, so avoid putting secrets in those fields.

Gateway authentication

maza init creates two random bearer credentials in OS storage:

• admin: access to the management API and dashboard.

• agent: MCP tool access to enabled tools, with no management access.

The nonsecret config stores credential references and token hashes. The service binds loopback, checks Host/Origin and verifies bearer tokens. Agent sessions have separate selection state and downstream protocol connections.

Stdio clients: run maza bridge. The bridge retrieves the agent credential from OS storage and authenticates to the shared service. You do not put a token into the MCP config.

HTTP clients: configure the endpoint http://127.0.0.1:47321/mcp with an Authorization: Bearer <token> header. Retrieve the agent token explicitly with:

maza token agent

Keep that token in your client's supported secret storage. The gateway uses local bearer authentication, not an inbound OAuth login flow. Clients that cannot configure a bearer header can use the stdio bridge. Do not expose this local service publicly.

Restricted gateway clients

Stop the daemon before changing clients. Wait until maza stop has finished shutting down the process before starting it again.

maza stop
maza client add reader files/read_text_file files/list_directory
maza start

Configure that client to launch maza bridge --client reader, or retrieve its HTTP token using maza token reader. Both the client's allowlist and each tool's enablement must permit an action. Omitting tool IDs from client add grants access to all enabled tools.

To revoke a client:

maza stop
maza client revoke reader
maza start

Client changes require a restart. A selected tool is not user authorization: the calling host remains responsible for obtaining any required approval for an action.

Downstream HTTP API keys

Store the complete header value using hidden input:

maza secret set service/bearer

At the prompt, enter the provider's complete header value, such as Bearer YOUR_PROVIDER_TOKEN. Create service.local.json with a reference, not the secret:

{
  "id": "service",
  "type": "http",
  "url": "https://example.com/mcp",
  "headerRefs": {
    "Authorization": "service/bearer"
  }
}

Then add and discover it:

maza add json service.local.json
maza discover service
maza tools service
maza enable service/tool_name

For providers using X-API-Key, use that header name and store the raw API key as its referenced value. Choose a new connection ID if service already exists; onboarding does not overwrite existing entries.

Downstream environment credentials

maza secret set provider/api-key

Create a connection file such as provider.local.json:

{
  "id": "provider",
  "type": "stdio",
  "command": "/absolute/path/to/node",
  "args": ["/absolute/path/to/provider-mcp-server.js"],
  "envRefs": {
    "PROVIDER_API_KEY": "provider/api-key"
  }
}

maza add json provider.local.json
maza discover provider

The server receives only configured credential bindings and a small base environment, not the gateway's entire environment. Literal env and headers are rejected by add json; use references. env:VARIABLE_NAME references are also supported, but the variable must exist in the daemon's environment when it starts. OS storage is simpler for the background service.

Downstream OAuth

For a provider supporting MCP OAuth with a public client:

maza add http oauth-service https://example.com/mcp --oauth
maza login oauth-service
maza discover oauth-service

Open the authorization URL printed by login. The local callback uses http://127.0.0.1:47322/callback; the CLI waits up to three minutes. The SDK handles discovery, dynamic registration where supported, PKCE exchange and token refresh. Registration data and tokens are kept in OS storage.

For a pre-registered public client:

maza add http oauth-service https://example.com/mcp --oauth --client-id YOUR_CLIENT_ID

The provider must allow the callback URL. Provider-specific authentication, confidential-client secrets, device grants and nonstandard OAuth are not implemented. The adapter has protocol tests; real-provider OAuth interoperability has not yet been validated.

Import an existing MCP config

maza stop
maza import /absolute/path/to/existing-mcp-config.json
maza start
maza discover

Import accepts a mcpServers map with local commands or HTTP URLs. Literal environment/header values are moved into OS storage, and only references are saved in Maza's config. Existing IDs are not overwritten, and discovered tools remain disabled until enabled. This does not support every host-specific config format.

Connect Claude Code

Start Maza, then run registration from the project where you want to use it:

cd /path/to/your/project
maza register-claude

This invokes claude mcp add --scope project to add the stdio bridge. It preserves unrelated MCP entries and does not write bearer tokens into .mcp.json. Use the same MAZA_HOME or --home as the running service.

Ask Claude to perform a task using an enabled tool, for example reading a file inside the allowed filesystem directory. The intended flow is:

1. find_tool with the immediate task and relevant context.

2. Inspect the returned original schema and resolve any shortlist or no-match response.

3. Generate the tool's arguments and call execute_tool with the returned selection and tool IDs.

The host plans multi-step tasks and repeats this flow for each next action. Maza supplies usage instructions but cannot force a host to adopt them.

For other stdio MCP clients, use a configuration like:

{
  "mcpServers": {
    "maza": {
      "command": "/absolute/path/to/node",
      "args": [
        "/absolute/path/to/maza/src/cli.js",
        "--home", "/absolute/path/to/maza-state",
        "bridge"
      ]
    }
  }
}

Service management and troubleshooting

maza status      # Authenticated status, discovered tools and recent activity.
maza stop        # Request graceful shutdown.
maza start       # Start a detached background process.
maza serve       # Run in the foreground instead.
npm test         # Run the protocol and access-control tests from this repository.

Do not run foreground and background instances on the same port. To change the port, stop the service, update port in the state directory's config.json, then restart. CLI and bridge read that same config. maza service-file generates an optional macOS launchd plist; it does not install login autostart automatically.

Transport failures and timeouts can occur after a downstream action has run. The gateway does not automatically retry execution; check the downstream state before retrying a mutation.

Scope

The proxy exposes tools only; it does not forward downstream resource/prompt browsing, sampling, elicitation, roots or task extensions. It uses the official MCP SDK, SQLite for schema/cache metadata, AJV for argument validation, and OS credentials for secrets. Diagnostics omit request arguments, results and credential values.

Jev routing includes a none-apply option and returns close candidates for resolution. Large catalogs are evaluated in bounded stages without truncating author descriptions. Routing thresholds are experimental and require workload-specific calibration. Fewer agent-visible definitions do not guarantee faster execution or lower cost, especially when a host caches its full tool catalog.

The repository contains implementation code, tests and local setup instructions. Machine-specific state, client config, benchmark data, transcripts and credentials are excluded. --test-stub exists only for explicitly labeled development plumbing; normal operation always uses Jev.