ToolBridge MCP
Optional adapter that swaps the fictional ticket tools onto a real Jira backend, so ticket listing, retrieval, creation and updates (with dry-run/confirm guardrails and audit logging) operate against Jira issues. Written against Atlassian's public API docs and only unit-tested with mocked HTTP, never run against a real Jira instance.
Optional adapter that backs the employee directory tools (directory search, employee lookup) with a real Slack workspace instead of the fictional data. Unit-tested only with mocked HTTP; not verified against a live Slack instance.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ToolBridge MCP who's on call for payments? draft an IT ticket to update the runbook"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 ( |
Accidental writes | Write tools ( |
Prompt injection | Text written by users (ticket bodies, wiki pages, comments) is wrapped in |
SQL |
|
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 |
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-erainitializehandshake still served for older clients. Both are tested.@modelcontextprotocol/server2.4.0,@modelcontextprotocol/node2.1.2,@modelcontextprotocol/client2.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/listOr 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 |
| viewer | Search returns public fields only (no phones); salary band only for admins |
| viewer | Returns |
| viewer | Filters, pagination, fenced user text |
| agent | Dry run unless |
| agent | Dry run unless |
| viewer | Weekly rotations, optional |
| viewer | Laptops and devices |
| agent | With policy notes (limits, receipts) |
| agent | Guarded read-only SQL over metrics, deployments, incidents, tickets |
| 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 whosetokenissha256:<hex>(fromtoolbridge-mcp token --role agent) orenv:VAR. Compared in constant time. The HTTP server refuses to start without at least one token.Origins:
--allow-origin https://example.com(repeatable) orTOOLBRIDGE_ALLOWED_ORIGINS;--playgroundaddshttps://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-mcpThe 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 blockhttp://localhostfrom 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 toolsasset_lookupLook up IT assetsARead-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 logARead-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 profileARead-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
directory_searchSearch the employee directoryARead-onlyIdempotent
Find employees by name, title, team, skill or location. Returns public profile fields only (no phone numbers). Paginated. Requires role: viewer.
Inputs: limit, query, cursor, location, +1 more. Returns: total, employees, next_cursor
expense_lookupLook up expense reportsARead-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)ARead-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 callARead-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 ticketARead-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 ticketsARead-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 ticketADestructiveIdempotent
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 pageARead-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
wiki_searchSearch the internal wikiARead-onlyIdempotent
Keyword search over HR, IT, finance and engineering wiki pages. Returns titles, a matching snippet and a wiki:// resource link for the full page. Requires role: viewer.
Inputs: query (required), limit. Returns: results
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
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.
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.
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.
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
Related MCP Connectors
Connect AI agents to 1000+ apps with managed authentication and tool-calling.
Governed AI agents for the software your company already runs. 400+ connectors, one endpoint.
One place to build, share, and govern the skills and tools your AI agents use at work.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceA production-grade platform that connects AI assistants to internal databases and filesystems through a single authenticated endpoint. It features role-based access control, SSO integration, and built-in tools for querying SQL databases and managing files with full audit logging.6MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to search HR policies, create IT support tickets, and send external emails with configurable security levels and human-in-the-loop validation.-
- FlicenseNot gradedqualityDmaintenanceProvides read-only access to Confluence, GitHub, Jira, Figma, Outlook, Teams, and browser automation for AI clients, enabling safe discovery, retrieval, and summarization of company knowledge without modifying source systems.-
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to search internal knowledge bases, create Confluence articles, file Jira tickets, and look up Okta users, with guardrails and streaming support.MIT