Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

feat(docs): add bridge documentation for early access#20188

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
stirby merged 13 commits intomainfromdk/bridge-docs
Oct 8, 2025
Merged
Show file tree
Hide file tree
Changes fromall commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
268 changes: 268 additions & 0 deletionsdocs/ai-coder/ai-bridge.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
# AI Bridge

> [!NOTE]
> AI Bridge is currently an _experimental_ feature.

![AI bridge diagram](../images/aibridge/aibridge_diagram.png)

Bridge is a smart proxy for AI. It acts as a man-in-the-middle between your users' coding agents / IDEs
and providers like OpenAI and Anthropic. By intercepting all the AI traffic between these clients and
the upstream APIs, Bridge can record user prompts, token usage, and tool invocations.

Bridge solves 3 key problems:

1. **Centralized authn/z management**: no more issuing & managing API tokens for OpenAI/Anthropic usage.
Users use their Coder session or API tokens to authenticate with `coderd` (Coder control plane), and
`coderd` securely communicates with the upstream APIs on their behalf. Use a single key for all users.
2. **Auditing and attribution**: all interactions with AI services, whether autonomous or human-initiated,
will be audited and attributed back to a user.
3. **Centralized MCP administration**: define a set of approved MCP servers and tools which your users may
use, and prevent users from using their own.

## When to use AI Bridge

As the library of LLMs and their associated tools grow, administrators are pressured to provide auditing, measure adoption, provide tools through MCP, and track token spend. Disparate SAAS platforms provide _some_ of these for _some_ tools, but there is no centralized, secure solution for these challenges.

If you are an administrator or devops leader looking to:

- Measure AI tooling adoption across teams or projects
- Provide an LLM audit trail to security administrators
- Manage token spend in a central dashboard
- Investigate opportunities for AI automation
- Uncover the high-leverage use cases from experienced engineers

We advise trying Bridge as self-hosted proxy to monitor LLM usage agnostically across AI powered IDEs like Cursor and headless agents like Claude Code.

## Setup

Bridge runs inside the Coder control plane, requiring no separate compute to deploy or scale. Once enabled, `coderd` hosts the bridge in-memory and brokers traffic to your configured AI providers on behalf of authenticated users.

**Required**:

1. A **premium** licensed Coder deployment
1. Feature must be [enabled](#activation) using the server flag
1. One or more [provider](#providers) API keys must be configured

### Activation

To enable this feature, activate the `aibridge` experiment using an environment variable or a CLI flag.
Additionally, you will need to enable Bridge explicitly:

```sh
CODER_EXPERIMENTS="aibridge" CODER_AIBRIDGE_ENABLED=true coder server
# or
coder server --experiments=aibridge --aibridge-enabled=true
```

_If you have other experiments enabled, separate them by commas._

### Providers

Bridge currently supports OpenAI and Anthropic APIs.

**API Key**:

The single key used to authenticate all requests from Bridge to OpenAI/Anthropic APIs.

- `CODER_AIBRIDGE_OPENAI_KEY` or `--aibridge-openai-key`
- `CODER_AIBRIDGE_ANTHROPIC_KEY` or `--aibridge-anthropic-key`

**Base URL**:

The API to which Bridge will relay requests.

- `CODER_AIBRIDGE_OPENAI_BASE_URL` or `--aibridge-openai-base-url`, defaults to `https://api.openai.com/v1/`
- `CODER_AIBRIDGE_ANTHROPIC_BASE_URL` or `--aibridge-anthropic-base-url`, defaults to `https://api.anthropic.com/`

Bridge is compatible with _[Google Vertex AI](https://cloud.google.com/vertex-ai?hl=en)_, _[AWS Bedrock](https://aws.amazon.com/bedrock/)_, and other LLM brokers. You may specify the base URL(s) above to the appropriate API endpoint for your provider.

---

> [!NOTE]
> See [Supported APIs](#supported-apis) section below for a comprehensive list.

## Collected Data

Bridge collects:

- The last `user` prompt of each request
- All token usage (associated with each prompt)
- Every tool invocation

All of these records are associated to an "interception" record, which maps 1:1 with requests received from clients but may involve several interactions with upstream providers. Interceptions are associated with a Coder identity, allowing you to map consumption and cost with teams or individuals in your organization:

![User Prompt logging](../images/aibridge/grafana_user_prompts_logging.png)

These logs can be used to determine usage patterns, track costs, and evaluate tooling adoption.

This data is currently accessible through the API and CLI (experimental), which we advise administrators export to their observability platform of choice. We've configured a Grafana dashboard to display Claude Code usage internally which can be imported as a starting point for your tooling adoption metrics.

![User Leaderboard](../images/aibridge/grafana_user_leaderboard.png)

We provide an example Grafana dashboard that you can import as a starting point for your tooling adoption metrics. See [here](../examples/monitoring/dashboards/grafana/aibridge/README.md).

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

🚫[linkspector]reported byreviewdog 🐶
Cannot reach ../examples/monitoring/dashboards/grafana/aibridge/README.md Status: 404 Cannot find: ../examples/monitoring/dashboards/grafana/aibridge/README.md


## Implementation Details

`coderd` runs an in-memory instance of `aibridged`, whose logic is mostly contained in https://github.com/coder/aibridge. In future releases we will support running external instances for higher throughput and complete memory isolation from `coderd`.

<details>
<summary>See a diagram of how Bridge interception works</summary>

```mermaid

sequenceDiagram
actor User
participant Client
participant Bridge

User->>Client: Issues prompt
activate Client

Note over User, Client: Coder session key used<br>as AI token
Client-->>Bridge: Sends request

activate Bridge
Note over Client, Bridge: Coder session key <br>passed along

Note over Bridge: Authenticate
Note over Bridge: Parse request

alt Rejected
Bridge-->>Client: Send response
Client->>User: Display response
end

Note over Bridge: If first request, establish <br>connection(s) with MCP server(s)<br>and list tools

Note over Bridge: Inject MCP tools

Bridge-->>AIProvider: Send modified request

activate AIProvider

AIProvider-->>Bridge: Send response

Note over Client: Client is unaware of injected<br>tools and invocations,<br>just receives one long response

alt Has injected tool calls
loop
Note over Bridge: Invoke injected tool
Bridge-->>AIProvider: Send tool result
AIProvider-->>Bridge: Send response
end
end

deactivate AIProvider

Bridge-->>Client: Relay response
deactivate Bridge

Client->>User: Display response
deactivate Client
```

</details>

## MCP

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) is a mechanism for connecting AI applications to external systems.

Bridge can connect to MCP servers and inject tools automatically, enabling you to centrally manage the list of tools you wish to grant your users.

> [!NOTE]
> Only MCP servers which support OAuth2 Authorization are supported currently. In future releases we will support [optional authorization](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#protocol-requirements).
>
> [_Streamable HTTP_](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) is the only supported transport currently. In future releases we will support the (now deprecated) [_Server-Sent Events_](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#backwards-compatibility) transport.

Bridge makes use of [External Auth](../admin/external-auth/index.md) applications, as they define OAuth2 connections to upstream services. If your External Auth application hosts a remote MCP server, you can configure Bridge to connect to it, retrieve its tools and inject them into requests automatically - all while using each individual user's access token.

For example, GitHub has a [remote MCP server](https://github.com/github/github-mcp-server?tab=readme-ov-file#remote-github-mcp-server) and we can use it as follows.

```bash
CODER_EXTERNAL_AUTH_0_TYPE=github
CODER_EXTERNAL_AUTH_0_CLIENT_ID=...
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=...
# Tell Bridge where it can find this service's remote MCP server.
CODER_EXTERNAL_AUTH_0_MCP_URL=https://api.githubcopilot.com/mcp/
```

See the diagram in [Implementation Details](#implementation-details) for more information.

You can also control which tools are injected by using an allow and/or a deny regular expression on the tool names:

```bash
CODER_EXTERNAL_AUTH_0_MCP_TOOL_ALLOW_REGEX=(.+_gist.*)
CODER_EXTERNAL_AUTH_0_MCP_TOOL_DENY_REGEX=(create_gist)
```

In the above example, all tools containing `_gist` in their name will be allowed, but `create_gist` is denied.

The logic works as follows:

- If neither the allow/deny patterns are defined, all tools will be injected.
- The deny pattern takes precedence.
- If only a deny pattern is defined, all tools are injected except those explicitly denied.

In the above example, if you prompted your AI model with "list your available github tools by name", it would reply something like:

> Certainly! Here are the GitHub-related tools that I have available:
>
> 1. `bmcp_github_update_gist`
> 2. `bmcp_github_list_gists`

Bridge marks automatically injected tools with a prefix `bmcp_` ("bridged MCP"). It also namespaces all tool names by the ID of their associated External Auth application (in this case `github`).

## Tool Injection

If a model decides to invoke a tool and it has a `bmcp_` suffix and Bridge has a connection with the related MCP server, it will invoke the tool. The tool result will be passed back to the upstream AI provider, and this will loop until the model has all of its required data. These inner loops are not relayed back to the client; all it seems is the result of this loop. See [Implementation Details](#implementation-details).

In contrast, tools which are defined by the client (i.e. the [`Bash` tool](https://docs.claude.com/en/docs/claude-code/settings#tools-available-to-claude) defined by _Claude Code_) cannot be invoked by Bridge, and the tool call from the model will be relayed to the client, after which it will invoke the tool.

If you have the `oauth2` and `mcp-server-http` experiments enabled, Coder's own [internal MCP tools](mcp-server.md) will be injected automatically.

### Troubleshooting

- **Too many tools**: should you receive an error like `Invalid 'tools': array too long. Expected an array with maximum length 128, but got an array with length 132 instead`, you can reduce the number by filtering out tools using the allow/deny patterns documented in the [MCP](#mcp) section.

- **Coder MCP tools not being injected**: in order for Coder MCP tools to be injected, the internal MCP server needs to be active. Follow the instructions in the [MCP Server](mcp-server.md) page to enable it.

- **External Auth tools not being injected**: this is generally due to the requesting user not being authenticated against the External Auth app; when this is the case, no attempt is made to connect to the MCP server.

## Known Issues / Limitations

- Codex CLI currently does not work with Bridge due to a JSON marshaling issue: https://github.com/coder/aibridge/issues/19
- Claude Code web searches do not report correctly: https://github.com/coder/aibridge/issues/11

## Supported APIs

API support is broken down into two categories:

- **Intercepted**: requests are intercepted, audited, and augmented - full Bridge functionality
- **Passthrough**: requests are proxied directly to the upstream, no auditing or augmentation takes place

Where relevant, both streaming and non-streaming requests are supported.

### OpenAI

**Intercepted**:

- [`/v1/chat/completions`](https://platform.openai.com/docs/api-reference/chat/create)

**Passthrough**:

- [`/v1/models(/*)`](https://platform.openai.com/docs/api-reference/models/list)
- [`/v1/responses`](https://platform.openai.com/docs/api-reference/responses/create) _(Interception support coming in **Beta**)_

### Anthropic

**Intercepted**:

- [`/v1/messages`](https://docs.claude.com/en/api/messages)

**Passthrough**:

- [`/v1/models(/*)`](https://docs.claude.com/en/api/models-list)

## Troubleshooting

To report a bug, file a feature request, or view a list of known issues, please visit our [GitHub repository for Bridge](https://github.com/coder/aibridge). If you encounter issues with Bridge during early access, please reach out to us via [Discord](https://discord.gg/coder).
Binary file addeddocs/images/aibridge/aibridge_diagram.png
View file
Open in desktop
Loading
Sorry, something went wrong.Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View file
Open in desktop
Loading
Sorry, something went wrong.Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View file
Open in desktop
Loading
Sorry, something went wrong.Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
7 changes: 7 additions & 0 deletionsdocs/manifest.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -907,6 +907,13 @@
"description": "Connect to agents Coder with a MCP server",
"path": "./ai-coder/mcp-server.md",
"state": ["beta"]
},
{
"title": "AI Bridge",
"description": "Centralized LLM and MCP proxy for platform teams",
"path": "./ai-coder/ai-bridge.md",
"icon_path": "./images/icons/api.svg",
"state": ["premium", "early access"]
}
]
},
Expand Down
39 changes: 39 additions & 0 deletionsexamples/monitoring/dashboards/grafana/aibridge/README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
# AI Bridge Grafana Dashboard

![AI Bridge example Grafana Dashboard](./grafana_dashboard.png)A sample Grafana dashboard for monitoring AI Bridge token usage, costs, and cache hit rates in Coder.

The dashboard includes three main sections with multiple visualization panels:

**Usage Leaderboards** - Track token consumption across your organization:
- Bar chart showing input, output, cache read, and cache write tokens per user
- Total usage statistics with breakdowns by token type

**Approximate Cost Table** - Estimate AI spending by joining token usage with live pricing data from LiteLLM:
- Per-provider and per-model cost breakdown
- Input, output, cache read, and cache write costs
- Total cost calculations with footer summaries

**Interceptions** - Monitor AI API calls over time:
- Time-series bar chart of interceptions by user
- Total interception count

**Prompts & Tool Calls Details** - Inspect actual AI interactions:
- User Prompts table showing all prompts sent to AI models with timestamps
- Tool Calls table displaying MCP tool invocations, inputs, and errors (color-coded for failures)

All panels support filtering by time range, username, provider (Anthropic, OpenAI, etc.), and model using regex patterns.

## Setup

1. **Install the Infinity plugin**: `grafana-cli plugins install yesoreyeram-infinity-datasource`

2. **Configure data sources**:
- **PostgreSQL datasource** (`coder-observability-ro`): Connect to your Coder database with read access to `aibridge_interceptions`, `aibridge_token_usages`, `aibridge_user_prompts`, `aibridge_tool_usages` and `users`
- **Infinity datasource** (`litellm-pricing-data`): Point to `https://raw.githubusercontent.com/BerriAI/litellm/refs/heads/main/model_prices_and_context_window.json` for model pricing data

3. **Import**: Download [`dashboard.json`](https://raw.githubusercontent.com/coder/coder/main/examples/monitoring/dashboards/grafana/aibridge/dashboard.json) from this directory, then in Grafana navigate to **Dashboards** → **Import** → **Upload JSON file**. Map the data sources when prompted.

## Features

- Token usage leaderboards by user, provider, and model
- Filterable by time range, username, provider, and model (regex supported)
Loading
Loading
[8]ページ先頭
©2009-2025 Movatter.jp