brighty-agent-toolkit

Banking infrastructure for AI agents. Use Brighty from Claude, Codex, Cursor, OpenClaw, or any MCP-compatible client to open accounts, issue cards, send SEPA/SWIFT payments, run mass payouts, and pay invoices — all through natural language.

This repository ships three things in one place:

• MCP server — exposes the Brighty API as 24 tools over stdio. Works with any MCP client.

• AgentSkills — four AgentSkills-spec skills (banking, payouts, invoice payment, card management) that teach an agent when and how to call the tools. Work in any AgentSkills-compatible client (Claude, Codex, Cursor, OpenClaw, ...).

• Anthropic plugin manifest — bundles the above for one-command install via /plugin marketplace add in Claude Code or Claude Desktop. The plugin wrapper is Anthropic-specific; the underlying MCP server and skills are not.

Specialized agents and slash commands for common workflows are planned for 0.1 — see the roadmap note below.

Quick start

Status: Published to npm as @brighty-app/mcp-server and installable as a Claude Code plugin from this GitHub repo. ClawHub publishing of individual skills is on the roadmap, not done.

Get a Brighty API key from the Brighty Business Portal — Owner role only. Set it as the BRIGHTY_API_KEY environment variable, or store it once in the OS keychain via the bundled login CLI (see Authentication).

Claude Code / Claude Desktop (recommended)

/plugin marketplace add razz-team/brighty-agent-toolkit
/plugin install brighty@brighty-agent-toolkit

This registers the stdio MCP server (via npx -y -p @brighty-app/mcp-server@<pinned-version> brighty-mcp — the -p form is required because the package ships two bins, brighty-mcp and brighty-mcp-login, neither of which matches the unscoped package name) and installs all four skills. The bundled .mcp.json pins the server version to match the plugin manifest version, so the npm dist-tag does not float independently of the plugin release. The two are kept in sync automatically by scripts/sync-versions.mjs when changesets bumps the package — see docs/CHANGESETS.md.

BRIGHTY_API_KEY and (optionally) BRIGHTY_API_URL are forwarded from the environment of whatever shell you launch Claude Code from — set them before launch.

Local checkout (development / unpublished features)

git clone https://github.com/razz-team/brighty-agent-toolkit
cd brighty-agent-toolkit
corepack enable
yarn install
yarn workspace @brighty-app/mcp-server build

Then point your MCP client command at node /absolute/path/to/brighty-agent-toolkit/packages/mcp-server/dist/index.js.

Skills only — any AgentSkills-compatible client

cp -r skills/* ~/.claude/skills/
# or ~/.codex/skills/, ~/.agents/skills/, etc.

The skills assume the Brighty MCP server is reachable over stdio — set it up in your client first, then drop the skill files in.

Ask your agent to install it

If you'd rather have your agent run the install for you, paste this prompt:

Install Brighty into this client. Read
https://github.com/razz-team/brighty-agent-toolkit/blob/master/AGENTS.md
and follow the path matching the client we're in.

AGENTS.md walks the agent through Claude Code, generic MCP clients, skill-only setups, and credential persistence.

What's inside

Skills

Each skill is self-contained and installs independently. They all assume the Brighty MCP server is reachable over stdio.

MCP server

packages/mcp-server is a TypeScript MCP server exposing 24 tools across accounts, payouts, transfers, cards, and members. Tool source lives in packages/mcp-server/src/tools/<domain>/<tool-name>.ts (one tool per file). The server runs over stdio as a subprocess of the agent client — this is the design, not a temporary state.

Alternative installation

Local stdio MCP only (no plugin)

npm install -g @brighty-app/mcp-server@latest

Then add to your client config (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "brighty": {
      "command": "brighty-mcp",
      "env": { "BRIGHTY_API_KEY": "your-key" }
    }
  }
}

For reproducible installs, pin the version explicitly instead of @latest — e.g. @brighty-app/mcp-server@0.0.2. The npx -y -p ... form in the plugin path always pins to a specific version via .mcp.json.

Authentication

The server reads the Brighty API key in this order:

1. BRIGHTY_API_KEY environment variable (preferred for CI, Docker, ephemeral hosts).

2. OS keychain entry brighty-mcp / default (preferred for personal workstations).

If neither is set, the server exits with an actionable error. There is no ~/.brighty/config.json and no MCP tool that writes credentials — credential mutation is intentionally an out-of-band CLI step. See docs/SECURITY.md for the full threat model.

To populate the keychain, run the bundled CLI:

# After a global npm install of @brighty-app/mcp-server (puts brighty-mcp on PATH):
brighty-mcp login

# From a local checkout (the bin is a workspace-only script, not on PATH):
yarn login

# Plugin / no-install path (uses the same CLI without a global install):
npx -y -p @brighty-app/mcp-server brighty-mcp login

# In every case:
# Brighty API key: <paste key>

The CLI validates the key against GET /accounts (the lightest authenticated endpoint on the Brighty Business API) before saving and masks it in any output. To clear the entry, delete the brighty-mcp item via your OS keychain UI (Keychain Access on macOS, secret-tool on Linux, Credential Manager on Windows).

To point the server at a non-production Brighty environment (staging, sandbox, mock), set BRIGHTY_API_URL to the full base URL including the API version path — defaults to https://api.brighty.app/business/v1. Example for the dev environment: BRIGHTY_API_URL=https://api.brighty.codes/business/v1.

Repository structure

.
├── .claude-plugin/
│   ├── marketplace.json     # plugin marketplace registration
│   └── plugin.json          # plugin manifest (skills + MCP server)
├── .mcp.json                # default MCP server connection (stdio)
├── packages/
│   └── mcp-server/          # TypeScript MCP server, 24 tools
├── skills/                  # AgentSkills-spec skills (publishable as-is)
│   ├── brighty-banking/
│   ├── brighty-payouts/
│   ├── brighty-invoice-pay/
│   └── brighty-cards/
├── docs/                    # SECURITY.md, plans/
└── scripts/                 # CI utilities (validate-plugin, check-tool-references)

Development

corepack enable
yarn install
yarn validate-plugin            # verify plugin manifest matches the file tree
yarn validate                   # validate all skills against AgentSkills spec
yarn check-tools                # ensure SKILL.md tool references match MCP source
yarn workspace @brighty-app/mcp-server build
yarn workspace @brighty-app/mcp-server test

CI runs the above on every PR. The cross-reference check between skill instructions and MCP tool definitions is the load-bearing invariant: renaming a tool without updating the corresponding skill fails the build.

Contributing

See CONTRIBUTING.md for the full guide. Short version: every PR has to keep the validate-plugin / validate / check-tools invariants green, every new MCP tool or schema change is cross-checked against the Brighty OpenAPI spec, and credential-mutating tools are off-limits (see docs/SECURITY.md).

Changelog

CHANGELOG.md — Keep a Changelog format. Bump notes for each release plus an [Unreleased] section for what's queued.

Security

Never commit API keys. The MCP server reads BRIGHTY_API_KEY from the environment or the OS keychain (entry brighty-mcp / default) — see Authentication. The server is stdio-only and intended for single-operator use on the operator's own machine — not for shared/public hosting.

Report security issues to security@brighty.app, not via public issues.

Roadmap

See docs/ROADMAP.md for what's shipped, what's planned for the next release, and what's deferred.

License

MIT for the MCP server source and skill instructions. See LICENSE. The Brighty name and logo remain property of Brighty Holding Ltd.

Links

• Brighty Business Portal — API keys

• Brighty API docs

• AgentSkills spec

• Claude Code plugin marketplaces