@bridge_gpt/mcp-server

MCP server for Bridge API — exposes Jira integration endpoints as MCP tools for AI coding agents. Works with Claude Code, VS Code/Copilot, Cursor, Windsurf, and OpenAI Codex.

Getting Started

1. Install the Package

From your project root, install the MCP server and scaffold slash commands:

npm i @bridge_gpt/mcp-server
npx -y @bridge_gpt/mcp-server --init

--init must be run from the directory containing your package.json. It:

• Creates slash commands in .claude/commands/ and .cursor/commands/
• Detects existing MCP config files and sets BAPI_PROJECT_ROOT so local file output resolves correctly
• Scaffolds .bridge/pipelines/ for custom pipeline authoring

Re-run --init after upgrading the package to get updated commands.

Upgrading

To upgrade to the latest version and refresh all scaffolded artifacts in one step:

npx -y @bridge_gpt/mcp-server --upgrade

This runs npm i @bridge_gpt/mcp-server@latest, prints a before/after version summary, then re-runs the full --init scaffolding flow to update your slash commands, agents, and pipeline definitions.

The MCP server also checks for updates automatically on startup. If a newer version is available, you'll see a notice in your editor's MCP output logs with the upgrade command to run. This check is cached for 24 hours and never blocks server startup.

2. Generate an API Key

1. Log in to Bridge API and navigate to your project's Security page
2. Click Create New Key
3. Enter your email, an optional label (e.g., "MCP Server"), and select the Admin role
4. Click Create Key
5. Copy the key immediately — it will not be shown again

3. Configure the MCP Server

Add the following to your editor's MCP configuration file, pasting in the API key from step 2:

The --init command (step 1) detects Claude Code and creates a .mcp.json at your project root with placeholder values. Open it and replace your-repo and your-api-key with your actual values from step 2:

{
  "mcpServers": {
    "bridge-api": {
      "command": "npx",
      "args": ["-y", "@bridge_gpt/mcp-server"],
      "env": {
        "BAPI_BASE_URL": "https://bridgegpt-api.com",
        "BAPI_REPO_NAME": "your-repo",
        "BAPI_API_KEY": "your-api-key",
        "BAPI_DOCS_DIR": "docs/tmp"
      }
    }
  }
}

{
  "servers": {
    "bridge-api": {
      "command": "npx",
      "args": ["-y", "@bridge_gpt/mcp-server"],
      "env": {
        "BAPI_BASE_URL": "https://bridgegpt-api.com",
        "BAPI_REPO_NAME": "your-repo",
        "BAPI_API_KEY": "your-api-key",
        "BAPI_DOCS_DIR": "docs/tmp"
      }
    }
  }
}

{
  "mcpServers": {
    "bridge-api": {
      "command": "npx",
      "args": ["-y", "@bridge_gpt/mcp-server"],
      "env": {
        "BAPI_BASE_URL": "https://bridgegpt-api.com",
        "BAPI_REPO_NAME": "your-repo",
        "BAPI_API_KEY": "your-api-key",
        "BAPI_DOCS_DIR": "docs/tmp"
      }
    }
  }
}

If project-local config is not supported in your Cursor version, use ~/.cursor/config/mcp.json instead.

Windsurf only supports global MCP configuration.

{
  "mcpServers": {
    "bridge-api": {
      "command": "npx",
      "args": ["-y", "@bridge_gpt/mcp-server"],
      "env": {
        "BAPI_BASE_URL": "https://bridgegpt-api.com",
        "BAPI_REPO_NAME": "your-repo",
        "BAPI_API_KEY": "your-api-key",
        "BAPI_DOCS_DIR": "docs/tmp"
      }
    }
  }
}

[mcp_servers.bridge-api]
command = "npx"
args = ["-y", "@bridge_gpt/mcp-server"]

[mcp_servers.bridge-api.env]
BAPI_BASE_URL = "https://bridgegpt-api.com"
BAPI_REPO_NAME = "your-repo"
BAPI_API_KEY = "your-api-key"
BAPI_DOCS_DIR = "docs/tmp"

Codex users: set BAPI_PROJECT_ROOT manually in your config (see Environment Variables below).

After saving the config, restart your editor or reload the MCP server connection. Verify connectivity by asking your AI assistant to call the ping tool.

First-Time Setup: Teach Bridge Your Codebase

If you're the first person to install Bridge API on your project, run the /learn-repository slash command after completing setup. This analyzes your codebase's architecture, testing patterns, code review standards, and documentation conventions, then uploads the findings to Bridge API. This gives Bridge the context it needs to generate implementation plans, ticket critiques, and code reviews that are consistent with your project's actual architecture and conventions.

You only need to do this once per project — the learned standards persist for all team members.

Pipelines

Pipelines are declarative, multi-step workflows that your AI agent executes step-by-step. Each pipeline is a JSON recipe that chains MCP tool calls and free-form agent tasks, with variable substitution, per-step error handling, and optional approval gates. Bridge ships with built-in pipelines; you can also write your own (see Custom Pipelines).

| Pipeline | Description | Invoke with | |---|---|---| | implement-ticket | Generate a plan, execute the implementation, commit, open a PR, and monitor CI | /implement-ticket PROJ-123 | | review-ticket | Two-round ticket quality review: clarifying questions and critique from multiple providers | /review-ticket PROJ-123 | | learn-repository | Analyze codebase architecture, testing patterns, review standards, and documentation conventions, then upload to Bridge | /learn-repository | | pr-ticket | Commit changes and open a pull request | /create-pr PROJ-123 | | check-ci-ticket | Commit, open a PR, then monitor CI checks until they pass or fail | /check-ci PROJ-123 |

Commands

Commands are slash commands you invoke from your AI assistant's chat. Most orchestrate multi-step workflows; some are simple single-action utilities. Run --init to scaffold them into your project.

| Command | Description | |---|---| | /check-ci [PROJ-123] | Monitor CI checks for the current branch, triage failures, apply fixes, and report results | | /check-parse-status | Check whether a background repository parse job is still running | | /clarify-ticket PROJ-123 | Generate clarifying questions for a ticket and save them locally | | /code-ticket PROJ-123 | Download the implementation plan and questions, then execute the plan inline | | /commit-ticket PROJ-123 | Stage, commit, and push changes; transition Jira status; post a smoke-test comment | | /create-pr PROJ-123 | Commit staged changes and open a pull request | | /critique-ticket PROJ-123 | Generate a ticket quality critique and save it locally | | /explore-ticket [PROJ-123] | Free-form codebase exploration — searches code, surfaces implementation options and questions | | /implement-ticket PROJ-123 | Full end-to-end implementation: plan → code → commit → PR → CI | | /learn-repository | Teach Bridge API about your codebase (architecture, testing, review patterns) | | /parse-repository | Queue a background job to index the repository for Bridge AI agents | | /plan-ticket PROJ-123 | Generate an AI implementation plan and save it locally | | /reimplement-ticket PROJ-123 | Follow-up implementation pass using previous implementation context | | /review-ticket PROJ-123 | Two-round ticket quality review with critiques from multiple LLM providers | | /run-tests | Run the full test suite, triage failures, and classify issues as test bugs vs. implementation bugs | | /scan-tickets | Sync recently-updated Jira tickets and backfill workflow timestamps | | /teach-bridge | Update a Bridge API configuration field via natural-language instructions | | /update-ticket PROJ-123 | Fetch clarifying questions and critique, then rewrite the ticket description and push to Jira | | /write-ticket | Draft a new Jira ticket from a prompt and upload it |

Commands are designed for Claude Code. Other editors may support slash commands differently — check your editor's documentation for how to invoke prompt files.

Available Tools

MCP tools are the low-level primitives Bridge exposes to your AI assistant. You don't call them directly — ask your AI assistant to perform the task you need, or compose them into a custom pipeline.

Connectivity

| Tool | Description | |---|---| | ping | Verify connectivity and confirm your API key is valid |

Jira Tickets

| Tool | Description | |---|---| | get_tickets | Search and list Jira tickets by query, status, or date | | get_ticket | Get full details for a single ticket | | create_ticket | Create a new Jira ticket | | add_comment | Post a comment on a ticket | | update_ticket_description | Replace a ticket's description | | upload_attachment | Upload a file as a ticket attachment |

AI Generation

Async tools follow a request/get pattern: call the request_* tool to kick off generation, then call the matching get_* tool to retrieve the result (or pass wait_for_result: true to poll automatically).

| Tool | Description | |---|---| | request_plan_generation | Request an AI-generated implementation plan | | get_plan | Retrieve a generated implementation plan | | request_architecture | Request an AI-generated architecture plan | | get_architecture | Retrieve a generated architecture plan | | request_clarifying_questions | Request clarifying questions for a ticket | | get_clarifying_questions | Retrieve generated clarifying questions | | request_ticket_critique | Request a ticket quality critique | | get_ticket_critique | Retrieve a generated ticket critique | | request_reimplement_context | Request context assembly for a follow-up implementation | | get_reimplement_context | Retrieve assembled reimplementation context | | request_deep_research | Submit a deep research query | | get_deep_research | Retrieve deep research results |

Ticket Lifecycle

| Tool | Description | |---|---| | track_ticket | Register a ticket for lifecycle tracking | | update_ticket_state | Update workflow timestamps for a tracked ticket | | get_ticket_state | Get workflow state and timestamps for a tracked ticket |

Jira Status

| Tool | Description | |---|---| | get_jira_transitions | List available status transitions for a ticket | | update_jira_status | Transition a ticket to a new Jira status | | resolve_target_status | Resolve the post-PR target status for a project |

Configuration

| Tool | Description | |---|---| | get_project_standards | Retrieve configured coding standards and architecture guidelines | | list_config_fields | List all available configuration fields | | get_config_field | Read the current value of a configuration field | | update_config_field | Update a configuration field | | get_my_role | Check the role and permissions for the current API key |

Repository & CI

| Tool | Description | |---|---| | parse_repository | Queue a background job to parse and index the repository | | get_parse_status | Check whether a repository parse is in progress | | regenerate_directory_map | Regenerate the repository directory map | | create_pull_request | Create a pull request on GitHub or Bitbucket | | resolve_ci_checks | Discover and classify CI checks for a commit | | poll_ci_checks | Poll the current status of CI checks |

Pipelines

| Tool | Description | |---|---| | get_docs_dir | Return the configured local docs directory path | | list_pipelines | List available pipeline recipes with names and descriptions | | get_pipeline_recipe | Retrieve a fully resolved pipeline recipe with variables substituted |

Custom Pipelines

You can create your own pipelines by adding JSON files to .bridge/pipelines/. Running --init scaffolds this directory with a README.md and an example pipeline to get you started.

The easiest way to write a custom pipeline is to describe what you want to automate to your AI coding agent and have it draft the JSON for you. The schema is straightforward, and agents like Claude Code understand it well — just describe the steps you want, and the agent will produce a working pipeline file.

What you can build:

• Any sequence of Bridge MCP tool calls and free-form agent tasks
• Parameterized workflows using variables (e.g., {ticket_key})
• Approval gates that pause for user confirmation before sensitive steps
• Per-step error handling — halt immediately or warn and continue

Ideas for custom pipelines:

• A standup pipeline that fetches your open tickets and summarizes their status
• A ticket triage pipeline that runs critiques on a batch of new tickets
• A pre-merge checklist that runs tests, checks linting, and posts a summary comment

Step types:

| Type | What it does | |---|---| | mcp_call | Calls an MCP tool with the given params | | agent_task | Gives the AI a free-form instruction (inline or from a file in .bridge/instructions/) |

Variables are declared in the variables array and referenced as {variable_name} in params and instructions. Each step supports on_error: "halt" (default) or "warn_and_continue", and requires_approval: true to pause before execution.

System variables:

Two variables are automatically available in every pipeline without declaring them:

| Variable | What it does | |---|---| | {provider} | Routes AI generation to a specific LLM provider (openai, anthropic, or gemini). Pass it through to any request_* tool param to control which provider handles that step. Omit it (or leave it empty) to use the project default. | | {second_opinion} | Runs AI generation through a different provider than the default, acting as a cross-check. Set to "auto" to let Bridge pick the second provider automatically. When set, it takes precedence over {provider}. Use this when you want two independent AI perspectives on the same task — for example, running clarifying questions and a critique twice (once with each provider) produces better results than a single pass. |

See .bridge/pipelines/README.md for the full schema reference.

If a custom pipeline has the same key as a built-in pipeline, the custom version takes precedence (a warning is logged at startup).

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | BAPI_BASE_URL | Yes | https://bridgegpt-api.com | Bridge API base URL | | BAPI_REPO_NAME | Yes | (none) | Jira project/repository identifier configured in Bridge API | | BAPI_API_KEY | Yes | (none) | API key obtained from the Bridge API setup UI | | BAPI_PROJECT_ROOT | No | (auto-set by --init) | Absolute path to project root. Anchors BAPI_DOCS_DIR and BAPI_PIPELINES_DIR resolution | | BAPI_DOCS_DIR | No | docs/tmp | Local directory for saving plans, critiques, and research reports | | BAPI_PIPELINES_DIR | No | .bridge/pipelines | Directory for user-defined custom pipeline JSON files |