MCP Servers - Allternit Docs

Overview

gizzi mcp manages Model Context Protocol (MCP) servers that extend the Allternit runtime with external tools and context sources. You can register local command-based servers, connect to remote HTTP servers, and handle OAuth authentication from the terminal. MCP servers declared through the CLI are written to your gizzi.json or gizzi.jsonc configuration, either in the current project or globally.

Protocol versions (2026-07-28 and older servers)

Gizzi speaks MCP 2026-07-28 and every earlier revision, using the official TypeScript SDK v2 (@modelcontextprotocol/client / server / core). You don’t configure anything: on the first connect to a server Gizzi sends server/discover.

Server	What Gizzi does
Speaks 2026-07-28	Stateless requests: each request carries the protocol version, client info and capabilities in `_meta`; no `initialize`, no session.
Older (2025-era) server	Falls back to the `initialize` handshake and a normal session, byte-for-byte what older clients send.
Legacy HTTP+SSE server	Connects over SSE with `initialize` (SSE predates 2026-07-28).

The verdict is cached per server in mcp-era.json in Gizzi’s data directory, keyed by the server’s URL or command:

A 2026-07-28 verdict skips the probe. Gizzi confirms it with one server/discover on the live connection. For local servers this saves spawning a second probe process.
An older-server verdict goes straight to initialize and expires after 24 hours, so an upgraded server is picked up the next day.
Changing a server’s URL or command, gizzi mcp auth, or gizzi mcp logout clears the cached verdict.

For a local (stdio) server, the first probe runs in a short-lived copy of the server process. A server that doesn’t answer within 5 seconds is treated as an older server. gizzi mcp list shows the result next to each connected server. For example, connected · 2026-07-28 is a 2026-07-28 server, and connected · legacy 2025-06-18 is an older one. To override detection for one server, set protocol on its entry:

`protocol`	Behavior
`auto` (default)	Probe with `server/discover`; fall back to `initialize`
`legacy`	Always use `initialize` (for a server that misbehaves when probed)
`modern`	Require 2026-07-28; fail instead of falling back

{
  "mcp": {
    "old-tools": {
      "type": "local",
      "command": ["node", "server.js"],
      "protocol": "legacy"
    }
  }
}

The behaviors below work the same in both protocol eras:

Tool names are namespaced as mcp__<server>__<tool>, in a stable order: servers by name, then each server’s tools by name. Name collisions get the same suffix on every run.
Approval flags (allternit/approved in _meta) are sent on tool calls.
The MCP Apps UI capability is sent to every server.
timeout applies to connecting and to requests.

Gizzi’s own MCP servers answer both protocol eras. This includes the knowledge-vault Lens server.

Command reference

Command	Alias	Description
`gizzi mcp list`	`ls`	List configured MCP servers and their connection status
`gizzi mcp add`	—	Add a new MCP server interactively
`gizzi mcp remove [name]`	`rm`	Remove an MCP server from config
`gizzi mcp auth [name]`	—	Authenticate with an OAuth-enabled remote MCP server
`gizzi mcp auth list`	`ls`	List OAuth-capable servers and their auth status
`gizzi mcp logout [name]`	—	Remove stored OAuth credentials for a server
`gizzi mcp debug <name>`	—	Debug OAuth connectivity for a remote MCP server

Listing servers

Show every configured server and its current status:

gizzi mcp list

Each entry displays:

Server name and type (local or remote)
Connection status: connected, disabled, needs authentication, failed, or not initialized
For remote servers, the target URL and whether OAuth credentials are stored
Error hints when a server failed to connect

Adding a server

Run the interactive wizard to register a server:

gizzi mcp add

The wizard prompts for:

Location — current project (gizzi.json or .gizzi/gizzi.json) or global config.
Name — a short identifier used in commands and runtime tool routing.
Type — local or remote.

Local server

For a local server, provide the shell command to start it:

Enter command to run: npx -y @modelcontextprotocol/server-filesystem ~/projects

This writes an entry like:

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "~/projects"]
    }
  }
}

Remote server

For a remote server, provide the HTTPS URL. You can then opt into OAuth and supply a pre-registered client ID and optional client secret, or leave the client ID empty and let Gizzi identify itself (see How Gizzi identifies itself to OAuth servers).

{
  "mcp": {
    "my-server": {
      "type": "remote",
      "url": "https://example.com/mcp",
      "oauth": {
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret"
      }
    }
  }
}

To disable OAuth for a remote server, set "oauth": false.

Removing a server

Remove a server interactively:

gizzi mcp remove

Or pass the name directly:

gizzi mcp remove filesystem

The command locates the config file that defines the server (project or global) and removes the entry while preserving JSONC comments.

Authenticating with OAuth

Remote MCP servers that require OAuth can be authenticated through the browser:

gizzi mcp auth my-server

If you omit the name, the CLI lists all OAuth-capable servers and lets you pick one. The command opens the provider’s authorization URL in your default browser and stores the tokens locally. If the browser cannot be opened automatically, the URL is printed so you can complete the flow manually. Check the current auth status at any time:

gizzi mcp auth list

Statuses shown are authenticated, expired, or not authenticated.

How Gizzi identifies itself to OAuth servers

When oauth.clientId is not set, Gizzi picks the first method the authorization server supports:

Client ID Metadata Document (CIMD). MCP 2026-07-28 prefers this method over dynamic client registration. If the authorization server advertises client_id_metadata_document_supported, Gizzi uses https://platform.allternit.com/oauth/gizzi-client.json as its client_id. That document lists Gizzi’s loopback redirect URIs (http://127.0.0.1:19876/mcp/oauth/callback and http://localhost:19876/mcp/oauth/callback). Nothing is registered and nothing is stored per server.
Dynamic client registration (RFC 7591). This is the fallback for servers without CIMD. MCP 2026-07-28 deprecates it, but Gizzi still supports it. The registered client is stored with the server’s tokens.
If the server supports neither method, gizzi mcp list shows needs client registration. Add a pre-registered clientId (and clientSecret if the server requires one) to the server’s oauth block.

A configured clientId always takes precedence. To turn CIMD off, set MCP_OAUTH_CLIENT_METADATA_URL to an empty string. To test against a different document, set it to that document’s URL. The authorization callback is checked against the issuer the flow started with (RFC 9207 iss), so a mixed-up or forged callback is rejected.

Logging out

Delete stored OAuth tokens and client registration for a server:

gizzi mcp logout my-server

Running logout without a name presents a picker for all servers that have stored credentials.

Debugging OAuth

Use debug to inspect the OAuth handshake and basic HTTP connectivity:

gizzi mcp debug my-server

The command prints:

Stored auth status and token expiry
Whether a refresh token is present
Client registration details
HTTP response status from the server
Which protocol era the server speaks. The probe is a server/discover request: a 2026-07-28 server lists its supported versions, and an older server rejects it.
WWW-Authenticate header analysis
Whether the OAuth flow can be triggered successfully

This is useful when a remote server shows needs authentication or failed in gizzi mcp list.

Server status reference

Status	Meaning
`connected`	The server is running and reachable. The protocol revision is shown after it, for example `· 2026-07-28` or `· legacy 2025-06-18`.
`disabled`	The server is configured but disabled
`needs authentication`	OAuth credentials are missing or expired
`needs client registration`	OAuth client registration is missing or invalid
`failed`	The server returned an error; see the printed hint
`not initialized`	The server is configured but has not been started yet

Common positional arguments

Argument	Commands	Description
`name`	`remove`, `auth`, `logout`, `debug`	Identifier of the MCP server as declared in config

Most mcp commands are interactive by default when name is omitted, except for debug where the name is required.

Configuration file locations

The CLI searches for a config file in this order inside the project:

gizzi.jsonc
gizzi.json
.gizzi/gizzi.jsonc
.gizzi/gizzi.json

If none exist, the wizard defaults to gizzi.json. For global scope it writes to the equivalent path under ~/.config/gizzi-code/.

Disabling MCP support

MCP support is enabled by default. To disable it for a session:

GIZZI_MCP_ENABLED=0 gizzi

Gizzi Code Overview — what the CLI is and how it fits into the Allternit platform
Configuration — config files, profiles, and environment variables
Headless Execution — running agents non-interactively with gizzi exec
Permission Profiles — controlling tool approval rules

​Overview

​Protocol versions (2026-07-28 and older servers)

​Command reference

​Listing servers

​Adding a server

​Local server

​Remote server

​Removing a server

​Authenticating with OAuth

​How Gizzi identifies itself to OAuth servers

​Logging out

​Debugging OAuth

​Server status reference

​Common positional arguments

​Configuration file locations

​Disabling MCP support

​Related docs