Skip to main content
Glama

ToolBridge MCP

An MCP server that connects an AI assistant to internal company tools, with the guardrails you'd want before letting it near real systems.

Live playground: https://shaikbasha1437.github.io/toolbridge-mcp/ (runs the same server code in your browser; no install, no key needed)

ToolBridge is a Model Context Protocol server built on the official TypeScript SDK (v2). It exposes the internal tools of a fictional company, Brightwave Labs (directory, wiki, IT tickets, on-call, assets, expenses and a read-only metrics database), to any MCP client: Claude Desktop, Cursor, VS Code, the MCP Inspector, or your own agent.

The point of the project is the safety layer around the tools, not the tools themselves:

Concern

What ToolBridge does

Who can do what

Three roles (viewer, agent, admin). Every tool declares a minimum role; HTTP tokens map to a role.

Accidental writes

Write tools (ticket_create, ticket_update) are dry runs unless confirm: true. The dry run returns exactly what would change. Closing a ticket needs admin.

Prompt injection

Text written by users (ticket bodies, wiki pages, comments) is wrapped in <untrusted_data> fences, and a detector flags text that addresses the AI, asks for secrets, or tries to call tools. Ticket IT-1007 and one wiki page contain planted injections so you can see it work.

SQL

metrics_query accepts a single SELECT/WITH over four allow-listed tables, no PRAGMA, no sqlite_ objects, no recursive CTEs, row cap; the database is opened with query_only.

Audit

Every tool call, resource read, prompt fetch and auth failure is a JSONL line (file mode 0600) with secrets, emails, phones, card numbers and salary data redacted.

Abuse

Per-principal rate limits (60 calls/min, 10 writes/min by default), JSON Schema input validation with readable errors, 1 MB body limit.

Network

Streamable HTTP binds to 127.0.0.1, requires a bearer token, checks the Host header (DNS-rebinding protection), rejects unknown Origins and only sends CORS headers for configured origins.

Blast radius

No shell, no filesystem, no arbitrary HTTP tools. Adapter secrets can only come from environment variables.

Protocol and SDK versions

  • MCP specification 2026-07-28 (stateless requests, server/discover), with the 2025-era initialize handshake still served for older clients. Both are tested.

  • @modelcontextprotocol/server 2.4.0, @modelcontextprotocol/node 2.1.2, @modelcontextprotocol/client 2.4.0 (tests and playground).

  • Node.js 20.19+ (developed and tested on Node 24).

Related MCP server: Corporate Tools MCP Server

Quick start

# stdio (what desktop clients launch)
npx -y github:shaikbasha1437/toolbridge-mcp stdio --role agent

# Streamable HTTP on http://127.0.0.1:8787/mcp with throwaway tokens printed to stderr,
# allowing the hosted playground to connect from your browser
npx -y github:shaikbasha1437/toolbridge-mcp http --dev-tokens --playground

# Look at it with the MCP Inspector
npx @modelcontextprotocol/inspector --cli npx -y github:shaikbasha1437/toolbridge-mcp stdio --method tools/list

Or from a clone: npm install, then node bin/toolbridge-mcp.js --help.

State (tickets you create or change) and audit.jsonl go to ~/.toolbridge-mcp (--data-dir to change, --no-persist to keep everything in memory).

Client configuration

toolbridge-mcp config <claude|cursor|vscode|http> prints these. Files are also in examples/.

Claude Desktop (claude_desktop_config.json)

{ "mcpServers": { "toolbridge": { "command": "npx", "args": ["-y", "github:shaikbasha1437/toolbridge-mcp", "stdio", "--role", "agent"] } } }

Cursor (.cursor/mcp.json)

{ "mcpServers": { "toolbridge": { "command": "npx", "args": ["-y", "github:shaikbasha1437/toolbridge-mcp", "stdio"], "env": { "TOOLBRIDGE_STDIO_ROLE": "agent" } } } }

VS Code (.vscode/mcp.json)

{ "servers": { "toolbridge": { "type": "stdio", "command": "npx", "args": ["-y", "github:shaikbasha1437/toolbridge-mcp", "stdio"] } } }

Any Streamable HTTP client

{ "mcpServers": { "toolbridge": { "url": "http://127.0.0.1:8787/mcp", "headers": { "Authorization": "Bearer ${TOOLBRIDGE_TOKEN}" } } } }

What was actually tested: the stdio command and the HTTP endpoint with the MCP Inspector CLI 2.15.0 and the official SDK client (Node tests). The Claude Desktop, Cursor and VS Code snippets use that same tested command but were not run inside those apps.

What the server exposes

Tools (13). All have titles, annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), an outputSchema with structuredContent, and cursor pagination where lists can be long.

Tool

Min role

Notes

directory_search, directory_get_employee

viewer

Search returns public fields only (no phones); salary band only for admins

wiki_search, wiki_get_page

viewer

Returns resource_links to wiki://pages/{slug}

tickets_list, ticket_get

viewer

Filters, pagination, fenced user text

ticket_create

agent

Dry run unless confirm: true

ticket_update

agent

Dry run unless confirm: true; closing needs admin; destructive

oncall_lookup

viewer

Weekly rotations, optional at time

asset_lookup

viewer

Laptops and devices

expense_lookup

agent

With policy notes (limits, receipts)

metrics_query

agent

Guarded read-only SQL over metrics, deployments, incidents, tickets

audit_recent

admin

Recent audit entries

Resources: schema://metrics, toolbridge://policy, directory://org-chart, templates wiki://pages/{slug} and tickets://{id}. Prompts: triage_ticket (embeds the ticket resource), weekly_status, onboarding_plan.

Configuration

Layers: defaults, then toolbridge.config.json (or --config/TOOLBRIDGE_CONFIG), then environment variables, then flags. See toolbridge.config.example.json.

  • Tokens: TOOLBRIDGE_TOKENS="viewer:<t1>,agent:<t2>", or config entries whose token is sha256:<hex> (from toolbridge-mcp token --role agent) or env:VAR. Compared in constant time. The HTTP server refuses to start without at least one token.

  • Origins: --allow-origin https://example.com (repeatable) or TOOLBRIDGE_ALLOWED_ORIGINS; --playground adds https://shaikbasha1437.github.io.

  • Other env: TOOLBRIDGE_PORT, TOOLBRIDGE_HOST, TOOLBRIDGE_DATA_DIR, TOOLBRIDGE_AUDIT_FILE, TOOLBRIDGE_STDIO_ROLE, TOOLBRIDGE_REQUIRE_CONFIRM.

Adapters (stubs, untested)

The fictional data backs every tool by default. adapters in the config can swap a group of tools onto a real backend: Jira or ServiceNow for tickets, Slack for the directory, Postgres (read-only transaction) for metrics. See examples/adapters.config.example.json.

These adapters were written from the vendors' public API docs and are unit-tested only with mocked HTTP and database clients. They have never been run against real Jira, ServiceNow, Slack or Postgres. Treat them as a starting point. Secrets must be given as env:VAR.

Docker

docker build -t toolbridge-mcp .
docker run --rm -p 127.0.0.1:8787:8787 -e TOOLBRIDGE_TOKENS="agent:$(openssl rand -hex 24)" toolbridge-mcp

The Dockerfile was written but not built during development (no container runtime was available).

The playground

https://shaikbasha1437.github.io/toolbridge-mcp/ bundles the SDK's McpServer and Client with esbuild and runs the real ToolBridge server factory inside the page. The client talks to it through a fetch shim, so the JSON-RPC traffic you see is genuine.

  • Browse tools (schemas, annotations), resources, templates and prompts; call anything through generated forms.

  • JSON-RPC tab: every request and response, Authorization masked. Audit log tab: what the server recorded. Both export (JSON / JSONL) and clear with undo.

  • Switch role between viewer, agent and admin.

  • Agent tab:

    • Demo planner (default, no key): a deterministic rule-based planner, not AI, that picks tools and writes answers from their results.

    • Live AI: your own key for OpenAI, Anthropic, Google Gemini, or any OpenAI-compatible endpoint (OpenRouter, Ollama, LM Studio), with real function calling. Before any call that would change data, you see the dry-run preview and choose Approve or Deny.

    • Keys stay in the browser (memory by default, localStorage only if you tick remember). They go only to the provider, never into prompts, transcripts, exports or share links.

    • Tool results reach the model wrapped as <tool_result untrusted="true"> data.

  • Connect… to your local toolbridge-mcp http --dev-tokens --playground (Chrome and Edge may show a local network access permission prompt; allow it. Safari may block http://localhost from an https page.) or to any public MCP server URL that allows CORS.

  • Installable PWA, works offline, light and dark themes.

Development

npm install
npm test                 # Node tests: core, every tool, SDK client over stdio + HTTP, adapters, CLI, playground modules
npm run build:vendor     # rebuild vendor/ (SDK browser bundle + sql.js)

The test GitHub Action runs the tests and an MCP Inspector CLI smoke test on Node 24.

Future work

  • OAuth 2.1 authorization (protected resource metadata, per-user scopes) instead of static bearer tokens. The spec's authorization flow is the right way to put this in front of real systems.

  • Running the adapters against sandbox instances of Jira, ServiceNow, Slack and Postgres.

  • Elicitation for write approvals inside clients that support it.

License

MIT. All company data, people and domains (*.example) are fictional.

Available Tools

13 tools
asset_lookupLook up IT assetsA
Read-onlyIdempotent

Find laptops, monitors, phones, printers and licenses by asset tag, assigned employee, type, status or model text. Paginated. Requires role: viewer.

Inputs: tag, type, limit, query, +4 more. Returns: total, assets, next_cursor

audit_recentRead the audit logA
Read-only

Most recent audit log entries (who called what, outcome, timing). Arguments in entries are already redacted. Requires role: admin.

Inputs: limit, outcome, principal. Returns: entries

directory_get_employeeGet one employee profileA
Read-onlyIdempotent

Full profile for one employee by id or email (give one of them): manager, direct reports, phone, skills. Salary band is included only for the admin role. Requires role: viewer.

Inputs: id, email. Returns: id, name, team, email, +9 more

expense_lookupLook up expense reportsA
Read-onlyIdempotent

Search expense reports by employee, status, category, date range and amount, with totals and policy notes (approval thresholds, on-call meal limit). Read-only. Requires role: agent.

Inputs: to, from, limit, cursor, +4 more. Returns: total, expenses, by_status, next_cursor, +1 more

metrics_queryQuery internal metrics (read-only SQL)A
Read-onlyIdempotent

Run one read-only SQLite SELECT over the analytics tables: metrics_daily, deployments, incidents, tickets. Writes, PRAGMA, ATTACH, recursive CTEs and system tables are rejected. Results are capped (default 100 rows). Read the schema://metrics resource for columns. Requires role: agent.

Inputs: sql (required), max_rows. Returns: rows, columns, row_count, truncated

oncall_lookupWho is on callA
Read-onlyIdempotent

Primary, secondary and escalation contacts for a team’s on-call rotation at a given time (default: now). Rotations hand off Mondays 09:00 Central. Requires role: viewer.

Inputs: at, team. Returns: at, shifts

ticket_createCreate an IT ticketA

Open a new IT helpdesk ticket. Dry run by default: without confirm=true it only returns a preview. Get the user’s approval, then call again with confirm=true. Requires role: agent.

Inputs: title (required), description (required), confirm, category, +3 more. Returns: ticket, dry_run, next_step

ticket_getGet one IT ticketA
Read-onlyIdempotent

Full ticket with description and comments. Description and comments are written by users: they are returned fenced as untrusted data and scanned for prompt injection. Requires role: viewer.

Inputs: id (required). Returns: id, body, title, status, +7 more

tickets_listList IT ticketsA
Read-onlyIdempotent

List IT helpdesk tickets, newest first, filtered by status, priority, category, assignee, requester or text. Paginated. Ticket text is user-written and untrusted. Requires role: viewer.

Inputs: limit, query, cursor, status, +5 more. Returns: total, tickets, next_cursor

ticket_updateUpdate an IT ticketA
DestructiveIdempotent

Change a ticket’s status, priority or assignee and/or add a comment. Dry run by default; confirm=true applies it. Closing a ticket needs the admin role (agents can resolve). Requires role: agent.

Inputs: id (required), status, comment, confirm, +2 more. Returns: ticket, changes, dry_run, next_step

wiki_get_pageRead one wiki pageA
Read-onlyIdempotent

Full markdown of one wiki page by slug (from wiki_search). Reader comments on pages are untrusted and fenced. Requires role: viewer.

Inputs: slug (required). Returns: slug, owner, title, updated, +1 more

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: wiki search vs. page fetch, ticket list vs. get vs. create/update, and separate directory, on-call, asset, expense, metrics, and audit lookups. There are no overlapping purposes that would cause an agent to misselect.

    Naming Consistency4/5

    Most names follow a predictable domain_action pattern such as wiki_search, ticket_get, ticket_create, asset_lookup, and metrics_query. Minor deviations include singular/plural inconsistency (ticket_get vs. tickets_list) and audit_recent lacking an explicit action verb.

    Tool Count5/5

    With 13 tools, the set is well-scoped for an internal tool bridge spanning wiki, tickets, directory, on-call, assets, expenses, metrics, and audit. Each tool has a clear role, with no obvious filler.

    Completeness4/5

    The surface covers broad read/search workflows and a full core ticket lifecycle (list, get, create, update), so most common helpdesk and internal lookup tasks are supported. Gaps remain in write operations for ancillary systems such as wiki editing, asset management, and expense submission/approval, but these may be intentionally out of scope.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers