Skip to main content
Glama

usemcpkit

Many MCP servers in one binary. Each server is a JSON manifest that describes its API, auth, tools and response mapping. A generic executor runs those manifests.

Repository layout

packages/core      @usemcpkit/core       library: manifest format, SDK, form contract (publishable)
packages/servers   @usemcpkit/servers    server definitions, compiled into the registry (private)
packages/testing   @usemcpkit/testing    shared test fixtures (private)
apps/runner        usemcpkit-runner      the usemcpkit binary: commands, installing, the supervisor (Rust)
apps/server        usemcpkit-servers     the usemcpkit-servers binary: MCP stdio server; opens the credentials window next to it (Rust)
apps/window        usemcpkit-window      the credentials window: a Tauri app with the Svelte page in apps/window/ui (@usemcpkit/ui, private)
apps/npx           usemcpkit             wrapper so `npx usemcpkit` runs the binary of this platform
apps/analytics     @usemcpkit/analytics  usage-reporting Worker
crates/*                                 the Rust libraries behind the binaries

Yarn 4 workspaces and Nx, Node 22.18+, and a Rust toolchain with cargo on PATH. Every command below runs from the repository root.

yarn install
yarn build          # every package; packages/servers/build/manifests/ + target/release/usemcpkit[-servers]
                    #   then a copy of every build and the Rust release binaries in build/
yarn test
yarn typecheck
yarn lint           # Biome: lint + format + import order check per project
yarn format         # Biome: apply formatting and safe fixes across the repo

Every package builds from src/main.ts into build/usemcpkit.<package>.js (usemcpkit.core.d.ts for the published types, usemcpkit.ui.html for the UI page). Nx runs lint, typecheck and test before every build, and builds dependencies first.

Related MCP server: Git MCP Server

Install

npx usemcpkit

This finds the AI clients installed for the current user, asks which ones to set up, copies the usemcpkit binary for this OS to ~/.usemcpkit/bin/usemcpkit and adds one mcpkit entry (<binary> serve, every server) to each chosen client. Running it again updates the entries in place, and replaces a usemcpkit entry 0.10 or 0.11 wrote. Only that key is touched: comments and other keys stay, and the previous file is kept as <config>.usemcpkit-backup. For Claude Code it also sets "agentPushNotifEnabled": true in ~/.claude/settings.json, the same way. Restart the clients afterwards (later updates reload live).

The client sees two tools, search and execute, whatever the servers (see "What the AI client sees"). Install then asks whether usemcpkit keeps itself up to date (on by default) and writes USEMCPKIT_AUTOUPDATE=1 or 0 the same way; --auto-update (or --auto-update=false) answers it without asking, and --all and --clients leave it on. Running install again rewrites the whole entry, so set any other variable of yours there again afterwards.

npx usemcpkit --all                         # every detected client, no checklist (needed without a terminal)
npx usemcpkit --clients cursor,codex        # only these
usemcpkit install --binary ./usemcpkit         # install a local binary instead of downloading one
usemcpkit install --all --auto-update=false    # every client, no scheduled upgrade and no self-update
usemcpkit uninstall [--all | --clients ...] # remove the entry; the binary stays
usemcpkit update                            # refresh the cached manifests now
usemcpkit upgrade                           # update the cached manifests, then the installed binary
usemcpkit config                            # print config.json with secrets and tokens masked, safe to paste

Supported clients (ids): claude-desktop, claude-code (~/.claude.json), cursor, vscode, vscode-insiders (servers in the user mcp.json), devin-desktop (Windsurf's new home), windsurf (legacy ~/.codeium/windsurf), cline (~/.cline), roo-code, copilot-cli, codex (TOML), gemini-cli, zed (context_servers), opencode (mcp), kiro, lm-studio, junie, warp. A client counts as installed when its config directory exists. Each client's path and entry shape lives in crates/clients/src/definitions/<id>.rs.

Where the binary comes from. npx usemcpkit runs the usemcpkit binary of the @usemcpkit/cli-<target> package npm installed for this machine (for example @usemcpkit/cli-darwin-arm64, @usemcpkit/cli-linux-x64-musl), which holds it, usemcpkit-servers and usemcpkit-window. Installing copies all three. A runner with no usemcpkit-servers beside it downloads @usemcpkit/cli-<target> at its own version from the npm registry and checks the tarball against its published sha512 integrity. Building and publishing those packages is release work, see docs/rust-port.md.

Auto-update. usemcpkit serve, when it is the installed binary, checks the npm registry at most every six hours (~/.usemcpkit/.updated-state) in the background: at start, and then every hour for as long as it runs, so a server that stays up for days still finds a new release. A newer release replaces the binary and is picked up without restarting the client, see Live reload. USEMCPKIT_AUTOUPDATE=0 turns this off and unloads the scheduled usemcpkit upgrade (the next serve removes it), 1 or unset loads it again; USEMCPKIT_NPM_REGISTRY points at another registry.

Live reload. A compiled usemcpkit serve is a small supervisor: it keeps the client's stdio connection and runs the real server as a worker (usemcpkit serve --worker). It polls its own binary file and, once the file was replaced and stayed the same for two polls (3 s each), starts the new binary as a second worker, replays the client's initialize handshake to it and only then switches new requests over. The old worker finishes the requests it already has (up to 5 minutes) and exits. The client is not notified, so it sees a changed server list in the description of search the next time it lists tools. The same applies when you copy a rebuilt binary over ~/.usemcpkit/bin/usemcpkit or when auto-update downloads a release. If the new binary fails to answer initialize within 15 s, the running server stays and the reason is logged to stderr. The supervisor itself is not swapped: a release that changes it needs one client restart. Calls always run on the new server. A Homebrew upgrade moves the binary to a new Cellar/<version> folder, so that install is not reloaded live.

Homebrew and winget. The package only installs the binary. Running usemcpkit afterwards shows the same client checklist. A binary under Homebrew's Cellar/usemcpkit/<version> is used in place: clients get <prefix>/bin/usemcpkit, the link Homebrew moves on every upgrade. A winget binary under WinGet\Packages\<id>_… is also used in place. Neither is copied to ~/.usemcpkit/bin or updated by usemcpkit; usemcpkit upgrade prints the brew upgrade / winget upgrade command instead. The Homebrew formula's caveats and the winget manifest's InstallationNotes should say "Run usemcpkit to set up your AI clients."

CLI

packages/servers/src/servers/gitlab/gitlab.ts   author servers in TypeScript (one folder per server, one tool per file)
  └─ vite build                          packages/servers: plugins/manifests/ compiles + validates src/servers/*
       └─ build/manifests/*.json          compiled manifests + index.json (the registry; CI publishes it to GitHub Pages)
cargo build --release -p usemcpkit-window  apps/window: the Tauri credentials window, with its Svelte page inside
cargo build --release                    apps/runner + apps/server, no manifests inside
  ├─ target/release/usemcpkit            commands and the supervisor that owns the client's stdio
  ├─ target/release/usemcpkit-servers    the MCP server it runs, which downloads manifests from the registry
  └─ target/release/usemcpkit-window     the credentials window it opens next to itself

An invalid server definition fails the build. The build log lists each compiled manifest:

usemcpkit: 1 manifest(s) → build/manifests
  github  1.0.0  1239 tools  bearer GITHUB_TOKEN  1.8 MB

Adding a server

Create packages/servers/src/<name>/<name>.ts with exactly one named export built with defineServer from @usemcpkit/core. Folder dashes become underscores in the server name (my-api → my_api). Put each tool in packages/servers/src/<name>/tools/<resource>/<action>.ts (the tool pull_request:list lives in tools/pull-request/list.ts) and shared params in const.ts.

Use with an MCP client

npx usemcpkit writes the entry for you (see Install). By hand:

{
  "mcpServers": {
    "mcpkit": {
      "command": "/Users/me/.usemcpkit/bin/usemcpkit",
      "args": ["serve"]
    }
  }
}

usemcpkit serve with no names serves every server; usemcpkit serve github only some. The client sees search and execute, which find and call the tools of those servers.

Bundled servers

Most servers are built from the OpenAPI (or Swagger 2.0) description of what the host runs, on your machine, the first time the server is opened (see "Servers built from OpenAPI" below). Their tools are named after their endpoint, <path>:<method>, the path as the description writes it without the leading / (repos/{owner}/{repo}/pulls:get), and grouped by its first segment.

Server

Category

Hosts

Tools

github

git

github.com, GitHub Enterprise Server

the GitHub REST API, built from the description of github.com or of the Enterprise Server version the host runs, for example repos/{owner}/{repo}/pulls:get, repos/{owner}/{repo}/issues:post

gitlab

git

gitlab.com, self-managed GitLab (<host>[/<relative url root>])

the GitLab REST API, built from the description of gitlab.com or of the release the host runs (its Swagger 2.0 file), for example api/v4/projects/{id}/issues:get, api/v4/projects/{id}/merge_requests/{merge_request_iid}/notes:post

jira

orgs/atlassian

Jira Cloud (<site>.atlassian.net), Jira Data Center 10.0 and later, and 9.x with a core set of hand-written tools

the Jira platform REST API (/rest/api/2) and Jira Software boards and sprints, built from the Cloud descriptions or from the one of the Data Center release the host runs, for example rest/api/2/issue:post, rest/api/2/search:get (Data Center) or rest/api/2/search/jql:get (Cloud), rest/agile/1.0/board:get

confluence

orgs/atlassian

Confluence Cloud (<site>.atlassian.net), Confluence Data Center 9.0 and later

the Confluence REST APIs, built from the Cloud v2 and v1 descriptions or from the one of the Data Center release the host runs, for example wiki/api/v2/pages:post and wiki/rest/api/search:get on Cloud, rest/api/content:post on Data Center

trello

orgs/atlassian

Trello (api.trello.com)

the Trello REST API with an API key and token, built from Atlassian's description, for example boards/{id}:get, boards/{id}/lists:get, cards:post, cards/{id}/actions/comments:post

clickup

productivity

ClickUp (api.clickup.com)

the ClickUp REST API v2 and v3, for example api/v2/list/{list_id}/task:get, api/v2/folder/{folder_id}/list:post, api/v3/workspaces/{workspace_id}/docs:get

discord

communication

Discord (discord.com/api/v10)

the Discord HTTP API v10 as a bot, for example channels/{channel_id}/messages:post, guilds/{guild_id}/members:get, users/@me/guilds:get

figma

design

Figma (api.figma.com)

the Figma REST API with a personal access token, for example v1/files/{file_key}/nodes:get, v1/files/{file_key}/comments:post, v1/files/{file_key}/components:get

n8n

automation

n8n Cloud (<name>.app.n8n.cloud), self-hosted n8n (<host>[/<path>], HTTPS); the MCP tools need n8n 1.120.0 or later

the n8n public REST API, for example workflows:get, workflows/{id}/activate:post, executions/{id}/retry:post; plus n8n's own instance-level MCP server (https://<host>/mcp-server/http, n8n 1.120.0 or later with MCP access turned on) as an HTTP upstream beside them, with its own one-click OAuth and its tools named <group>:<resource>:<action>, for example workflows:workflows:search, workflows:workflows:execute, builder:nodes:search, data_tables:rows:add (its tools are listed once the server is opened with codemode.tools("automation:n8n")); the MCP naming is in src/servers/n8n/mcp.ts

cloudflare

cloud

Cloudflare (mcp.cloudflare.com)

Cloudflare's own remote MCP server in code mode, reached as an HTTP upstream: api:spec:search and api:requests:execute take JavaScript that searches the OpenAPI spec and calls any Cloudflare API endpoint, plus docs:docs:search and account:account:whoami; see servers/cloudflare

postman

api

Postman (mcp.postman.com)

Postman's own remote MCP server in its Full mode (234 tools), reached as an HTTP upstream and opened by group: collections, environments, mocks, monitors, specs, workspaces, catalog, governance and more, for example collections:requests:create, environments:environments:list; see servers/postman

teams

communication

Microsoft Teams (Microsoft Graph)

the community Teams MCP server by Inditex, cloned on first use and run locally with uv, in the one team and channel it is configured for: channel:threads:start, channel:threads:update, channel:threads:read, channel:threads:list, team:members:list and team:members:get_by_name; see servers/teams

medium

communication

Medium (api.medium.com)

Medium's archived API, which needs an integration token you already have: me:get, users/{userId}/publications:get, publications/{publicationId}/contributors:get, users/{authorId}/posts:post, publications/{publicationId}/posts:post (HTML or Markdown, draft, unlisted or public) and images:post; it cannot read, edit or delete posts

GitLab reads GITLAB_HOST (default gitlab.com) and a personal access token in GITLAB_TOKEN. Tools take a project id or its full path (group/subgroup/project) as id, and issue and merge request numbers are the per-project iid.

Jira and Confluence ask for the host first (JIRA_HOST / CONFLUENCE_HOST, for example acme.atlassian.net or jira.example.com/jira), then for one of two options: Cloud: email + API token (JIRA_USERNAME + JIRA_API_TOKEN, CONFLUENCE_USERNAME + CONFLUENCE_API_TOKEN) or Data Center: personal access token (JIRA_PERSONAL_TOKEN, CONFLUENCE_PERSONAL_TOKEN). Cloud and Data Center use different endpoints where Atlassian removed the old ones on Cloud (Jira issue search); the host picks the descriptions its tools are built from, so a host has only the endpoints it serves. Confluence Cloud v2 tools take a space id (wiki/api/v2/spaces:get) instead of a space key. Data Center downloads an attachment with rest/api/2/attachment/content/{id}:get, a hand-written tool that takes the file name from the attachment's metadata, since Data Center serves the file from /secure/attachment/{id}/{filename}.

Trello reads an API key (a Power-Up's, from trello.com/power-ups/admin) in TRELLO_API_KEY and a token generated for that key in TRELLO_TOKEN, and sends both as the key and token query parameters of every call. The token's scope and expiry (read, write, account) decide what the AI can do. Atlassian's description names OAuth scopes on most endpoints; the key and token serve them all.

ClickUp reads a personal API token (pk_…, from Settings → Apps) in CLICKUP_API_TOKEN and sends it as the Authorization header. The v2 tools call the Workspace id team_id (api/v2/team:get lists them), and array filters such as statuses take a list.

Discord reads a bot token (Developer Portal → your application → Bot) in DISCORD_BOT_TOKEN and sends it as Authorization: Bot <token>; the bot must be in a guild to reach its channels. Ids are snowflakes passed as strings. The five endpoints that accept only a user's OAuth2 token are left out. To read message text, turn on the privileged Message Content intent on the Bot page; without it Discord returns other users' guild messages with an empty content.

Figma reads a personal access token (figd_…, Settings → Security → Personal access tokens, with the scopes you need such as File content or Comments) in FIGMA_ACCESS_TOKEN and sends it as X-Figma-Token. A file key is the part after /design/ in a Figma link, and a node id looks like 1:2 (node-id=1-2 in a link). v1/files/{file_key}:get returns the whole document and can be enormous: read parts with v1/files/{file_key}/nodes:get and ids, or pass depth. The nine operations that accept only an OAuth app or an organization plan token (teams, folder metadata, logs, AI usage, duplicating a file) are left out, and variables need an Enterprise plan.

n8n asks for the instance host first (N8N_HOST, for example acme.app.n8n.cloud or n8n.example.com/automation; the field also offers app.n8n.cloud and localhost:5678, neither picked by default), then for an API key (n8n → Settings → n8n API) in N8N_API_KEY, sent as X-N8N-API-KEY to https://<host>/api/v1. A localhost or 127.0.0.1 host is reached over http://, since a local n8n has no certificate; any other host needs HTTPS. The instance must have the public API enabled. The key's scopes (enterprise plans) or its user's role decide what the AI can do, and licensed features (source control, SSO, LDAP, log streaming, promotions, policies) answer 403 on instances without them. Deprecated operations (activateWorkflow, deactivateWorkflow) are left out; publish and unpublish a workflow instead.

n8n's REST API takes only an API key, so the MCP server beside the REST tools has its own sign-in (upstream.auth, see "Server manifests"); a call to a REST tool never starts it and never opens the browser. It uses the same host (N8N_HOST), then offers "Sign in with OAuth2": usemcpkit finds n8n's sign-in from the server's OAuth metadata, registers itself with the instance (see "OAuth for MCP servers" below), and you approve the permissions in n8n's consent screen. An instance admin must first turn on MCP access (Settings → Instance-level MCP → Enable MCP access); the sign-in needs n8n 1.120.0 or later. Without OAuth it reads an MCP access token (Settings → Instance-level MCP → Connect → API key tab) in N8N_MCP_TOKEN, sent as a bearer token; the REST API key does not work there. If an admin limited OAuth to trusted callback URLs (Allowed callback URLs → Only trusted URLs), add http://127.0.0.1/callback: n8n matches a loopback callback on any port. Clients only reach workflows enabled for MCP, apart from workflows:workflows:search, which previews every workflow the user can see. Which tools exist depends on the instance's version, license and settings (the workflow builder, agents, skills, folders) and on the permissions granted at sign-in. Tools older instances serve under earlier names (get_execution, list_tags, …) get the same names, and a tool n8n adds later stays tools:<name> until src/servers/n8n/mcp.ts names it.

Cloudflare signs in with one click: the first call opens the credentials window, whose "Sign in with OAuth2" button runs Cloudflare's own sign-in in the browser (see "OAuth for MCP servers" below). It also reads an API token (Cloudflare dashboard → My Profile → API Tokens, user or account token) in CLOUDFLARE_API_TOKEN and sends it as a bearer token to https://mcp.cloudflare.com/mcp. The token decides what the AI can do: api:requests:execute runs any call it allows, so grant only the permissions you want, and give an account token Account Resources: Read so the server finds the account id. Tokens with Client IP Address Filtering are not supported.

Postman signs in with one click through its own OAuth (see "OAuth for MCP servers" below), or reads an API key (Postman → Settings → API keys, PMAK-…) in POSTMAN_API_KEY and sends it as a bearer token to https://mcp.postman.com/mcp, the Full mode of Postman's server; the key decides what the AI can see and change. The EU region (mcp.eu.postman.com) is not used. A tool Postman adds later stays tools:<name> until servers/postman/const.ts names it, and the server then opens as one flat list.

Medium reads an integration token (medium.com → Settings → Security and apps → Integration tokens) in MEDIUM_INTEGRATION_TOKEN and sends it as a bearer token to https://api.medium.com/v1. Medium has archived this API and no longer issues new tokens, so the server works only for people who already have one. It can only create posts (arguments are named as in Medium's docs, for example contentFormat and publishStatus; publish as draft to keep one private), list publications and upload images; there is no tool to read, edit or delete a post.

Teams signs in as a Microsoft Entra application (a bot), not as you, and posts into one channel. It needs git and uv on PATH (uv installs its own Python 3.12 for it, never the system one). The first call opens the same credentials window as the other servers, with a field and a hint for each of TEAMS_APP_ID, TEAMS_APP_PASSWORD, TEAMS_APP_TENANT_ID, TEAM_ID and TEAMS_CHANNEL_ID and links to your Entra app registrations and the server's setup guide; the values are saved once the server has started with them. Setting them in the client's env for usemcpkit skips the window. Microsoft's own Teams MCP server (Work IQ) is not used: it needs a signed-in Entra OAuth token that usemcpkit cannot get.

Manifest format

{
  "name": "github",                       // [a-z][a-z0-9_]*
  "category": "git",                      // [a-z][a-z0-9-]*, groups servers of one kind
  "version": "1.0.0",
  "baseUrl": "https://{domain}",          // https only; {domain} is optional, see Domain
  "domain": { "label": "GitHub API host", "default": "api.github.com", "env": "GITHUB_API_HOST" },
  "headers": { "Accept": "application/vnd.github+json" },
  "auth": [                               // tried top to bottom, see Auth
    { "type": "bearer", "env": "GITHUB_TOKEN" }
  ],
  "tools": [
    {
      "name": "list_issues",
      "description": "List issues in a repository.",
      "input": { "type": "object", "properties": { ... }, "required": ["owner", "repo"] },
      "request": {
        "method": "GET",
        "path": "/repos/{owner}/{repo}/issues",  // {arg} → URL-encoded argument
        "query": ["state", "per_page"],          // or { "q": "query" } to rename
        "body": ["title"],                       // JSON body for non-GET, see Request bodies
        "commaQuery": ["tags"],                  // optional: array query keys joined with commas (others repeat the key)
        "fileArgs": ["file"],                    // optional: args holding a local file path; sent as multipart parts (contentType multipart/form-data) or as the raw bodyArg
        "saveToArg": "save_to",                  // optional: arg holding a local path; a successful response is written there and a summary returned
        "fixedQuery": { "sort": "updated" },     // optional: constant query values
        "contentType": "text/plain",             // optional: default application/json; text/* sends bodyArg as plain text
        "fixedHeaders": { "X-Atlassian-Token": "no-check" }, // optional: constant request headers
        "fixedBody": { "type": "issue" },        // optional: constant body values, args win
        "bodyArg": "body"                        // optional: send this arg as the whole JSON body (array, string or free-form object); excludes body/fixedBody
      },
      "response": {
        "root": "items",                         // optional: dig into the payload
        "fields": { "author": "user.login", "labels": "labels[].name" }
      }
    }
  ]
}

Request bodies. Outgoing body keys may be dotted paths that build nested JSON, with numbers as array indexes: { "fields.project.key": "project_key", "ancestors.0.id": "parent_id" } sends {"fields":{"project":{"key":"..."}},"ancestors":[{"id":"..."}]}. fixedBody keys work the same way. Fixed values are strings, numbers or booleans.

Editions. One server can cover deployments whose endpoints differ, such as Atlassian Cloud and Data Center. The manifest names them with the host suffixes that select them; a tool overrides its request (and response, when given) per edition. A domain matching no edition uses the tool's own request:

"editions": { "cloud": { "label": "Cloud", "hosts": [".atlassian.net"] } },   // names: [a-z][a-z0-9-]*
"tools": [
  {
    "name": "search_issues",
    "request": { "method": "GET", "path": "/rest/api/2/search", "query": ["jql"] },
    "editions": {
      "cloud": { "request": { "method": "GET", "path": "/rest/api/2/search/jql", "query": ["jql"] } }
    }
  }
]

The edition follows the domain in use, including one typed in the credentials form.

Servers built from OpenAPI

A manifest with openapi lists the descriptions its tools are built from instead of the tools themselves. The tools are built on your machine the first time the server is opened (codemode.tools("<server>") signs in first, as a call does), for the host in use and the version it runs, and kept in ~/.usemcpkit/manifests/openapi/<category>/<name>/ (hosts.json, the downloaded description as YAML, the built tools as JSON). The version is asked again after a day, and a new manifest builds them again. Until then search lists the server with a note and no tools.

"openapi": {
  "sources": [
    // every source whose hosts match the domain is used, their tools merged in order;
    // when none matches, every source without hosts
    { "name": "cloud", "hosts": [".atlassian.net"], "url": "https://…/swagger.v3.json" },
    {
      "name": "datacenter",
      "label": "Data Center",                                // what the credentials form calls it
      "url": "https://…/jira_software_dc_{version}_swagger.v3.json",
      "basePath": "",                                        // the path of the description's first server otherwise
      "version": {
        "probe": { "path": "/rest/api/2/serverInfo", "field": "version", "match": "^(\\d+\\.\\d+)" },
        "env": "JIRA_VERSION",                               // pins the version instead of asking the server
        "known": { "10.3": "10003", "11.3": "11003" }        // or "list": { "url", "items", "field", "match" }
      },
      "options": { "filePartName": "file", "skip": ["^\\w+ /rest/auth/"] }
    }
  ]
}
  • A url without {version} should carry its sha256; a url without a scheme names a document in the server's folder, which the registry publishes next to the manifest (Reddit and Medium, which publish no description).

  • With no description for the exact version, the nearest older one is used, with a warning. A version older than every description gets only the hand-written tools that apply to it (also with a warning), and is an error when none does: Jira Data Center 9.x has a core set (issues, JQL search, comments, transitions, attachments, worklogs, links, fields, projects, users, boards and sprints) under the names 10.0 builds.

  • Swagger 2.0 descriptions (GitLab releases) are converted to OpenAPI 3 first.

  • options tunes the conversion: maxDepth, includeDefaults, stripBold, widenMixedScalars, keepsExplodedArrays, descriptionPrefix, downloadPaths, filePartName, skip (regexes over METHOD /path), skipDeprecated, security (the schemes the auth satisfies) and fixedQuery.

  • A tool is named <path>:<method> after the path its requests go to below the base URL. The manifest's own tools replace built tools of the same name; applies limits one to some deployments, which is how a mistake of a description is fixed: sources names OpenAPI sources and if is a condition on the version the host runs, 9.0 <= {version} < 10 or {version} >= 9.0 && {version} < 10 (<, <=, >, >=, ==, !=). A tool of the server's MCP upstream wins over a built one of the same name.

  • An auth entry's applies limits it to some sources and versions in the credentials form. domain.check: true puts a Check button after the host field, which asks the host its version with what was typed so far and offers only the options that fit.

Auth

auth lists OAuth2 entries (oauth) first, then fallbacks. A server can use fallbacks only:

"auth": [
  { "type": "oauth", "authorizationUrl": "...", "tokenUrl": "...", "clientId": "..." },   // optional
  { "type": "bearer", "env": "GITHUB_TOKEN" }                                            // fallback
]

Every tool call tries, in this order, and uses the first that works:

  1. the server's OAuth2 token (signIn in config.json), refreshed if it expired (only when auth has oauth entries);

  2. each fallback whose value is set, top to bottom. A value comes from its env var, or else from config.json;

  3. the credentials form: a local page opened in the browser that asks for the missing values (and the domain, see below), or offers "Sign in with OAuth2" when the server has oauth entries.

An option is skipped when its credentials are missing or the API answers 401. A fallback that worked is tried right after the saved token on later calls in the same process. If nothing works, the call fails with one line per option saying why. none can only be the last entry. Leaving out auth means no auth.

Fallbacks. The manifest never holds a secret, only where to find it: none, bearer {env}, header {env, name, prefix?}, query {env, name}, basic {usernameEnv, passwordEnv} (each also takes an optional label, the option's title in the form; all but none take an optional ui, see below). Env vars always win, so CI keeps working without a browser.

Credentials form. usemcpkit serve starts a one-off server on 127.0.0.1 (a free port), prints its URL to stderr and opens the browser. Only the page that was opened can answer: the URL carries a session token in its #fragment and the server checks it and the Host header. Concurrent calls share one form; it closes after an answer, on Cancel, or after 5 minutes. Secrets are saved only after the API accepts them, so a typo is never stored.

Config file. The hosts and the saved credentials live together in ~/.usemcpkit/config.json, by category, server and host ({ "servers": { "git": { "gitlab": { "hosts": { "git.acme.com": { "secrets": { "GITLAB_TOKEN": "glpat-…" } } }, "projects": { "/work/app": "git.acme.com" } } } } }), which you can edit by hand. Credentials never cross hosts. With several hosts for one server, the host of a call is, in order: its env var; the host its project (git root) was bound to the first time you answered the form; the saved host the project's origin remote points at (servers whose manifest sets domain.matchGitRemote, such as GitHub and GitLab); otherwise the form asks, and the answer is remembered for that project. Credentials are plain text, with file mode 0600 in a 0700 directory, the way gh and glab keep their tokens. The file carries a version (1 until the 1.0 release); the keys are written sorted, each host and sign-in with a savedAt time, and a file from a newer usemcpkit is refused rather than overwritten. usemcpkit config prints it with every secret and token masked, safe to paste in an issue. There is no password and nothing to unlock. Any program running as your user can read the file, so protect your account and disk; to forget a credential, delete its entry or the file. Environment variables always win over the file.

Form UI. The page holds no text of its own. The CLI injects the whole view model, built from the manifest, into the page as JSON, and the page only renders it. Wording and buttons come from the manifest through defineUI:

import { defineServer, defineUI } from '@usemcpkit/core';

defineServer({
  // ...
  ui: defineUI({ texts: { title: 'Connect {server}', submit: 'Save' } }), // any key of the default texts
  auth: [
    {
      type: 'bearer',
      env: 'GITHUB_TOKEN',
      ui: defineUI({
        inputs: { GITHUB_TOKEN: { label: 'Token', hint: '…', placeholder: 'ghp_…' } },
        actions: [
          { type: 'link', label: 'Create on GitHub ↗', url: 'https://{webHost}/settings/tokens/new?name=usemcpkit+{server}' },
          { type: 'cli', label: 'Use GitHub CLI', command: 'gh', args: ['auth', 'token', '--hostname', '{webHost}'] },
        ],
      }),
    },
  ],
});
  • texts (on the manifest) overrides the defaults in core (DEFAULT_UI_TEXTS); {server} is filled in. domain also takes hint and placeholder.

  • inputs (on an auth entry, keyed by env var name) sets a field's label, hint and placeholder.

  • A link action opens an https:// URL. {domain} is the typed domain, {webHost} its web host (api.github.com → github.com, api.<name>.ghe.com → <name>.ghe.com, <host>/api/v3 → <host>), {server} the server name. The link follows the domain field and stays hidden while it needs a domain and there is none.

  • A cli action carries its own command and args; core has no list of tools. command must be a program name found on PATH (no path, no arguments), and args may use {domain} and {webHost}. On click the CLI process, not the page, runs it without a shell, with a 15 s timeout; the token it prints goes straight to the API check and never reaches the browser. It is offered only for an entry with a single credential, and only when the program is on PATH when the form opens. Nothing runs without the click.

GitLab offers Use GitLab CLI, which runs glab config get token --host <host>. Create on GitLab ↗ opens the personal access token page of the server's host (<host>/-/user_settings/personal_access_tokens, under the relative URL root if the domain has one), prefilled with a name and the api scope.

The CLI button is offered only for options with a single field. A domain typed in the form is used once it is valid. An imported token is saved like a typed one: only after the API accepts it. Manifests can be updated remotely (see below), so only use a registry you trust: its cli buttons name the programs usemcpkit runs when you click them.

Domain. A server whose host differs per user (GitHub Enterprise, self-hosted GitLab, Jira...) writes {domain} in baseUrl and, if it has them, in the OAuth URLs (discovery too) and an HTTP upstream's url, and declares domain:

"domain": { "label": "GitHub API host", "default": "api.github.com", "env": "GITHUB_API_HOST" }   // all optional

The domain comes from the env var, else config.json, else default. The form shows it prefilled and lets the user change it (host[:port][/path], no scheme), unless the env var is set. suggestedHosts lists hosts the field offers after the saved ones (n8n offers app.n8n.cloud and localhost:5678); offering one does not pick it. With loopbackHttp: true, a localhost or 127.0.0.1 domain is reached over http:// in baseUrl, the upstream and OAuth URLs and {domain} links; every other server stays on https://, even on localhost.

OAuth 2.0 with PKCE. The user signs in once in the browser against the provider directly:

{
  "type": "oauth",
  "authorizationUrl": "https://example.com/oauth/authorize",   // https only, {domain} allowed
  "tokenUrl": "https://example.com/oauth/token",               // https only, {domain} allowed
  "clientId": "public-client-id",
  "clientSecretEnv": "EXAMPLE_CLIENT_SECRET",                  // optional, for providers that need one
  "scopes": ["read", "write"],                                 // optional
  "redirectPort": 8976                                         // optional, 0 picks a free port
}

The sign-in starts on the first tool call that has no working token: usemcpkit serve prints the URL to stderr and opens the browser. The redirect goes to http://127.0.0.1:<port>/callback, and the authorization code is exchanged with a S256 code verifier. The token is saved as the server's signIn in ~/.usemcpkit/config.json (USEMCPKIT_HOME overrides) with file mode 0600, together with the entry that issued it. Tool calls send it as a Bearer token and refresh it before it expires. Concurrent calls share one sign-in. If the MCP client gives up waiting, the sign-in still finishes and the next call uses the token.

OAuth for MCP servers (one click, no app to register). An oauth entry that names only the MCP server needs no endpoints and no client id:

{ "type": "oauth", "discovery": "https://mcp.example.com/mcp" }   // https only, {domain} allowed

On the first call without a token, usemcpkit asks the server where it signs in (the protected resource metadata of RFC 9728 named by its /.well-known/oauth-protected-resource, then the authorization server's metadata of RFC 8414), registers itself there as a public client (RFC 7591, no secret) for a loopback redirect on a free port, and runs the same PKCE sign-in as above: one click on "Sign in with OAuth2" in the credentials window, or none when the entry is the server's only auth, approve in the browser tab that opens, and the tab closes itself where the browser allows it. The registered client id is saved as oauthClients in ~/.usemcpkit/config.json by issuer, and refreshes use it. A clientId next to discovery skips the registration, for a server that does not register clients itself. cloud:cloudflare, api:postman and automation:n8n (in its upstream.auth) carry this entry before their token fallback. The url may contain {domain} like baseUrl (https://{domain}/mcp-server/http for n8n), filled with the host in use, and over http:// for a loopback host when the manifest sets domain.loopbackHttp; a token signed in on one host is not sent to another.

Server manifests

No manifest ships inside the binary. They live in a registry (by default the repository's GitHub Pages, published by .github/workflows/release-registry.yml, a job of the Release workflow that deploys the manifests the Release build already produced; the build restores the Nx cache, so only changed projects are built):

Each release reads only the manifests published with it: a binary of version X.Y.Z reads https://mdreal32.github.io/mcpkit/vX.Y.Z/, so a binary that stays on an old version never gets manifests a newer one changed. Every deploy publishes the registry it just built both at the root (what 0.12.0 and older read) and under v<version>/ of the version being released, and unpacks the registry.tar.gz asset of every earlier GitHub Release into its own v<version>/ again, since GitHub Pages replaces the whole site (.github/scripts/assemble-registry-site.sh). Each folder holds:

index.json                  every server: id, version, description, link, sha256 (no tools, so it stays small)
<category>/<server>.json    one manifest, for example git/gitlab.json
<category>/<server>/<group>.json  with grouped tool names (git/github.json is a shell listing git/github/<group>.json)

Only index.json is synced by default (into ~/.usemcpkit/manifests, one cache for every version, USEMCPKIT_HOME overrides the home). A manifest is downloaded the first time a tool of that server is described or called, checked against the sha256 in the index, and cached.

  • usemcpkit install and the first serve/list with nothing cached download the index.

  • The cache is always served, and opening a server or calling a tool never asks the registry for changes. ~/.usemcpkit/manifests/cache.json maps each cached file (index.json, git/github.json, git/github/issues.json, ...) to updatedAt (ms, when its content last changed), checkedAt (ms, when it was last confirmed current) and its sha256; the index entry also notes the registry folder it was fetched from. Only a download that fails its checksum, because the cached index is older than the registry, fetches the index again once, and an index fetched from another registry folder (another version after an upgrade, or another USEMCPKIT_REGISTRY) is synced once before it is served, and kept if that sync fails.

  • usemcpkit update [--registry <url>] refreshes the index and re-downloads the manifests and parts that are already cached and no longer match it, so an edit published without a version bump still lands. A server or part nobody opened is never downloaded. The URL comes from the flag, USEMCPKIT_REGISTRY (both name the registry folder itself, no version is added), then the folder of this version.

  • usemcpkit upgrade runs that update and then replaces the installed binary. It is what the scheduled job runs every six hours, so manifests and binary stay current without anyone running a command. USEMCPKIT_AUTOUPDATE=0 turns the binary auto-update off and removes the scheduled job.

  • Self-hosting a registry is hosting the packages/servers/build/manifests/ folder and pointing USEMCPKIT_REGISTRY at it; every link in it is relative to that folder (the binaries default to DEFAULT_REGISTRY_URL in crates/registry plus v<version>).

What the AI client sees

The client sees two tools whatever the servers, in the style of Cloudflare's Code Mode, and nothing is loaded when the server starts:

  • search (read-only) runs an async arrow function, such as async () => { ... }, that looks the tools up: codemode.servers(), codemode.groups(server) and codemode.tools(server?, group?), which resolves to { id, description, inputSchema } for each tool. With no server, codemode.tools() returns every tool at once, so the code can filter all of them in one pass; the tools of an upstream are in that list once it was started, in this run or an earlier one whose tool list is cached, and codemode.tools("<id>") starts one that is not (a server with tools of its own, such as n8n, lists those always and says in the console output when its upstream could not be started). Given the start of a tool id instead of a server, codemode.tools("git:gitlab:api/v4/projects/{id}/merge_requests") returns the tools whose ids start with it, downloading only the group the prefix names. Its description lists the served servers.

  • execute runs the same kind of function with codemode.call(id, args) as well, which runs a tool by its full id (git:github:repos:repos:list_branches) and resolves to its result: a registry tool's JSON, or an upstream tool's structured content or text (parsed when it is JSON). A tool that fails throws an Error.

A server's shell, group files and upstream tools are loaded only when the code asks for them: each file is downloaded once into ~/.usemcpkit/manifests, and an upstream (Bitwarden, Cloudflare, n8n's MCP server, Postman, Teams) is started only when the code looks up or calls its tools. A server that cannot be loaded makes the code throw, with the reason, and the next call tries again. The code runs in QuickJS (rquickjs), a fresh runtime per call with no network, file or module access, 64 MB of memory and a 120-second limit that interrupts a busy loop as well as a slow tool. The function's return value is the structuredContent of the MCP CallToolResult (resultType: "complete"), exactly as returned and nowhere else, so the code should filter and pick fields before it returns. The text content holds only the console.log lines (cut at 24000 characters, about 6000 tokens, ending in --- TRUNCATED ---) and a thrown error. The client's permission rules only see search and execute, not the tools the code calls.

Ids still come from index.json: <category>:<server>:<resource>:<action> selects <category>/<server>.json. usemcpkit serve [servers…] limits the catalog to the given ids or bare names.

Debugging a connection

When a client does not show usemcpkit's tools, a call never returns, or a connection drops, turn on the wire log: set USEMCPKIT_DEBUG=1 in the environment the client starts usemcpkit with (the server entry's env, or the user environment, then quit and reopen the client so its processes see it). Every serve process then appends one JSON line per message and lifecycle event to its own file under ~/.usemcpkit/logs, named <role>-<start time>-<pid>.jsonl. A compiled binary writes two: the supervisor that owns the client's stdio and the server worker it runs. Each line records the time, the process and its parent (pid, ppid), the event and the message's id, method, called tool, the client's name from initialize, its error and its size. It never records arguments, results, credentials or environment values, so a log can be shared as it is. It can stay on: every start adds new files, so clear old ones from time to time, and unset the variable to stop writing them.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A unified MCP server with composable tools for GitHub operations, file management, shell execution, kanban boards, Discord messaging, and package management. Features role-based security, HTTP/stdio transports, and a web-based development UI.
      GPL 3.0
    • A
      license
      B
      quality
      D
      maintenance
      A modular MCP server that provides a unified interface for interacting with GitHub and GitLab, including enterprise and self-hosted instances. It enables comprehensive management of repositories, issues, pull requests, and CI/CD pipelines through natural language.
      23
      43 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A modular MCP server exposing tools for integrating with services like GitHub, Redash, Jenkins, Figma, Jira, Confluence, Teams, Datadog, PagerDuty, Slack, and Presto, enabling users to manage these platforms through natural language via an MCP client.
      -