mcpkit
Integrates with Confluence Cloud and Confluence Data Center to search content with CQL, get, create and update pages, list spaces, and list page children.
Integrates with the GitHub REST API (github.com, GitHub Enterprise Server, and GHE.com) to read the authenticated user and repositories, list and fetch issues, create issues, list pull requests, and search repositories.
Integrates with GitLab (gitlab.com or self-managed instances) to fetch the current user, list and get projects, list/get/create issues and add issue comments, list and get merge requests and add merge request comments, and list pipelines.
Integrates with Jira Cloud and Jira Data Center to fetch the current user, search issues with JQL, get, create, comment on and delete comments on issues, list transitions and transition issues, and list projects.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 binariesYarn 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 repoEvery 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 usemcpkitThis 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 pasteSupported 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 itselfAn 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 MBAdding 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.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 |
|
| gitlab.com, self-managed GitLab ( | 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 |
|
| Jira Cloud ( | the Jira platform REST API ( |
|
| Confluence Cloud ( | 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 |
|
| Trello ( | the Trello REST API with an API key and token, built from Atlassian's description, for example |
|
| ClickUp ( | the ClickUp REST API v2 and v3, for example |
|
| Discord ( | the Discord HTTP API v10 as a bot, for example |
|
| Figma ( | the Figma REST API with a personal access token, for example |
|
| n8n Cloud ( | the n8n public REST API, for example |
|
| Cloudflare ( | Cloudflare's own remote MCP server in code mode, reached as an HTTP upstream: |
|
| Postman ( | Postman's own remote MCP server in its Full mode (234 tools), reached as an HTTP upstream and opened by group: |
|
| 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: |
|
| Medium ( | Medium's archived API, which needs an integration token you already have: |
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 itssha256; 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.
optionstunes the conversion:maxDepth,includeDefaults,stripBold,widenMixedScalars,keepsExplodedArrays,descriptionPrefix,downloadPaths,filePartName,skip(regexes overMETHOD /path),skipDeprecated,security(the schemes the auth satisfies) andfixedQuery.A tool is named
<path>:<method>after the path its requests go to below the base URL. The manifest's owntoolsreplace built tools of the same name;applieslimits one to some deployments, which is how a mistake of a description is fixed:sourcesnames OpenAPI sources andifis a condition on the version the host runs,9.0 <= {version} < 10or{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
applieslimits it to some sources and versions in the credentials form.domain.check: trueputs 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:
the server's OAuth2 token (
signIninconfig.json), refreshed if it expired (only whenauthhasoauthentries);each fallback whose value is set, top to bottom. A value comes from its env var, or else from
config.json;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
oauthentries.
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.domainalso takeshintandplaceholder.inputs(on an auth entry, keyed by env var name) sets a field'slabel,hintandplaceholder.A
linkaction opens anhttps://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
cliaction carries its owncommandandargs; core has no list of tools.commandmust be a program name found on PATH (no path, no arguments), andargsmay 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 optionalThe 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} allowedOn 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 installand the firstserve/listwith 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.jsonmaps each cached file (index.json,git/github.json,git/github/issues.json, ...) toupdatedAt(ms, when its content last changed),checkedAt(ms, when it was last confirmed current) and itssha256; the index entry also notes theregistryfolder 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 anotherUSEMCPKIT_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 upgraderuns 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=0turns the binary auto-update off and removes the scheduled job.Self-hosting a registry is hosting the
packages/servers/build/manifests/folder and pointingUSEMCPKIT_REGISTRYat it; every link in it is relative to that folder (the binaries default toDEFAULT_REGISTRY_URLincrates/registryplusv<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 asasync () => { ... }, that looks the tools up:codemode.servers(),codemode.groups(server)andcodemode.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, andcodemode.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.executeruns the same kind of function withcodemode.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 anError.
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…
This server cannot be deployed
Maintenance
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
A MCP server built for developers enabling Git based project management with project and personal…
One MCP server for all your work accounts: Slack, Teams, Google Chat, Jira, ClickUp, digest, tasks.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA 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
- AlicenseBqualityDmaintenanceA 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.2343 npmMIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables interaction with Jira to fetch issues by key and perform JQL searches. It provides a foundation for integrating multiple work systems, with planned support for Slack and GitHub.ISC
- FlicenseNot gradedqualityDmaintenanceA 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.-