Using BridgeMCP

BridgeMCP has two primary consumption paths after your organization is set up:

• LLM-backed agents run jobs inside BridgeMCP. They combine model access, packaged instructions, isolated workspaces, and tools from a Virtual MCP.
• MCP clients connect directly to a Virtual MCP endpoint. They authenticate to BridgeMCP and call namespaced tools through the gateway.

Use this page as the shortest path from setup to a working agent or client. For deeper configuration details, follow the links in each section.

Use LLM-backed agents

Agents are best when you want BridgeMCP to run the LLM loop for you: queue a job, let the agent reason with a model, call tools, write artifacts, and return a session trace.

1. Configure model access

Choose the LLM provider and model the agent should use. BridgeMCP agents can run against configured model providers such as OpenAI, Anthropic, Gemini, or Ollama Cloud, depending on which providers your instance enables.

Keep provider credentials in the console or deployment configuration, not in agent packages or source control. The agent only needs to know which model configuration it should use.

2. Create or deploy an agent

Create an agent in the console, or package and deploy one with the CLI. An agent package contains the instructions and skills that define how the agent should behave; BridgeMCP supplies the runtime, workspace isolation, LLM access, and tool access.

The CLI is useful when you want agent definitions to live beside application code or be deployed from automation. See CLI usage for login, deployment, and status commands.

3. Attach a Virtual MCP tool surface

Attach the agent to a Virtual MCP that contains only the connectors and tools it needs. This is the main permission boundary for agent tool access: the agent can see the tools exposed by that Virtual MCP, and tool calls are recorded by the gateway.

Use connector tool overrides to disable noisy or risky tools, or to rewrite descriptions so the model has clearer instructions. See Connectors and Virtual MCPs and MCP endpoints for how aggregation and namespacing work.

4. Submit jobs

Submit a job with a prompt, optional metadata, optional input files, and optional timeout or callback settings. Each job gets its own isolated workspace:

input/     files submitted with the job
scratch/   intermediate working files
output/    artifacts the agent produced

Jobs do not share memory or workspace state. If you need repeatable behavior, put the durable instructions in the agent package and pass job-specific context in the job input.

5. Review outputs, sessions, and usage

After a job finishes, review its reply, output artifacts, and structured session trace. The session shows LLM responses, tool calls, tool results, and system events as inspectable cells.

Tool calls and job execution remain audited and reported as organization usage. Review current-period and historical counts in the console, and keep Virtual MCPs scoped so agents only call the tools they need.

Read next: Agents and jobs for the full job lifecycle, Webhook triggers for event-driven jobs, and Authentication and security for key and OAuth handling.

Use MCP-compatible clients

MCP clients are best when you want an external LLM application to own the conversation while BridgeMCP owns tool aggregation, authentication, routing, and auditing.

1. Create connectors

Add the upstream tool servers you want BridgeMCP to aggregate. A connector can be a hosted Streamable HTTP MCP server, a legacy upstream that still requires HTTP+SSE compatibility, a managed stdio package launched with npx or uvx, a built-in connector, or a custom HTTP tool surface. Choose Streamable HTTP for new remote connectors.

For each connector, configure its outbound authentication separately from client access. For example, a GitHub connector may need OAuth to GitHub, while the MCP client still authenticates inbound to BridgeMCP with an API key or inbound OAuth token.

2. Group connectors into a Virtual MCP

Create a Virtual MCP for the client, team, environment, or workflow. Add only the connectors the client should see. BridgeMCP exposes the Virtual MCP as a single Streamable HTTP MCP endpoint:

https://bridgemcp.net/api/v1/mcp/{virtual-mcp-id}

Keep this exact URL for every supported MCP revision. Modern clients use stateless 2026-07-28 requests and older clients use the compatible initialize flow; the client negotiates automatically.

When a client lists tools, BridgeMCP combines tools from every connector in the Virtual MCP and prefixes each tool with the connector name, such as github.pull_request_read.

3. Choose inbound authentication

Use one of the supported inbound auth methods:

• API key: create a key scoped to one Virtual MCP and send it as Authorization: Bearer brg_live_sk_....
• Inbound OAuth: use an interactive MCP client that supports OAuth discovery, Client ID Metadata Documents (CIMD) or Dynamic Client Registration (DCR), PKCE, and browser consent.

API keys are simplest for local and scripted clients. Inbound OAuth is better for interactive clients that can send the user through consent without copying secrets.

4. Configure the MCP client

Point the client at the Virtual MCP endpoint and include the inbound credential if you are using an API key. For example:

{
  "mcpServers": {
    "bridge-dev": {
      "url": "https://bridgemcp.net/api/v1/mcp/{virtual-mcp-id}",
      "headers": {
        "Authorization": "Bearer brg_live_sk_..."
      }
    }
  }
}

Do not commit real API keys or OAuth tokens to client configuration files. Store them in a local secret manager or environment-specific config when the client supports it.

5. Call namespaced tools

Once connected, the client can list and call tools through the gateway. Use namespaced tool names exactly as BridgeMCP returns them. BridgeMCP routes each call to the correct connector, records activity, and returns the upstream result to the client.

If a tool is missing, check that the connector is enabled, connected, included in the Virtual MCP, and not disabled by a tool override.

Read next: MCP endpoints for routing details, Connectors and Virtual MCPs for connector setup, Custom HTTP tools for exposing your own APIs, and Authentication and security for inbound and outbound auth.

Which path should I choose?

Most teams use both paths: MCP clients for interactive work, and agents for repeatable jobs that need durable instructions, isolated files, and reviewable outputs.