Connect the MCP server

BIMP provides a remote Model Context Protocol (MCP) server so compatible assistants can check container images and prepare remediation plans against your organization’s live published policy.

The MCP tools are advisory and do not change policy, BIMP configuration, or repository files. Your assistant should show proposed edits and follow the repository’s normal review process.

Before you connect

You need:

• access to a BIMP environment where MCP is included and enabled;
• membership in an organization with permission to read its policy or organization context;
• an MCP client that supports remote Streamable HTTP servers and OAuth; and
• the repository name, branch, and file path for the artifact you want to evaluate.

Find the server URL

In BIMP, open Settings → Automation → MCP. Copy the remote MCP endpoint shown for the current environment:

https://<your-bimp-host>/api/v1/mcp

Use the endpoint shown in BIMP instead of copying one from another environment. OAuth access tokens are bound to the server you connect.

Connect Codex

The MCP page provides commands with the correct host. Run:

codex mcp add bimp --url https://<your-bimp-host>/api/v1/mcp
codex mcp login bimp

The login command opens BIMP’s OAuth authorization flow. Sign in, review the requested access, and approve the client.

Register BIMP as a native remote MCP server. Do not wrap it with npx mcp-remote, because Codex supports the server’s OAuth flow directly.

Connect another MCP client

For a client that accepts MCP JSON, start with:

{
  "mcpServers": {
    "bimp": {
      "url": "https://<your-bimp-host>/api/v1/mcp"
    }
  }
}

The endpoint publishes protected-resource and authorization-server metadata. A compatible client discovers the OAuth flow from that metadata, so you do not need to paste an access token into the configuration.

Tell your assistant when to use BIMP

MCP servers advertise their tools and instructions, but the client model still decides when to call them. Add the following rule to the repository’s AGENTS.md or equivalent instruction file:

Before editing Dockerfiles, devcontainer.json, Compose files, or Helm values
image references, or answering questions about approved mappings, base images,
or container image policy, call BIMP MCP get_remediation_plan with
repository_full_name, branch_name, file_path, and current file_content. Use
check_image_compliance for specific image checks. Do not guess approved target
images from model knowledge.

Pass the current local file content whenever it is available. BIMP prefers that content over the last scanned state, which keeps checks accurate for uncommitted edits.

Available tools and prompt

check_image_compliance

Use this tool to check whether an image or supported artifact is approved, current, mapped, or otherwise governed by live BIMP policy.

Required inputs:

• repository_full_name
• branch_name
• file_path

Optional inputs:

• organization_id
• repository_provider, either github or gitlab
• file_type, one of dockerfile, devcontainer, compose, or helm_values
• file_content
• image
• platform

get_remediation_plan

Use this tool before changing a Dockerfile, devcontainer file, Compose file, or supported Helm values file. It returns exact replacement records and operational policy context for the current artifact.

Required inputs:

• repository_full_name
• branch_name
• file_path

Optional inputs:

• organization_id
• repository_provider, either github or gitlab
• file_type, one of dockerfile, devcontainer, compose, or helm_values
• file_content

fix_container_images_with_bimp_policy

This prompt asks an MCP client to fix supported container image references using live BIMP policy. It accepts the repository name, branch, file path, and optional current file content.

Choose the organization

If your account can access one organization, BIMP can resolve that context. If you can access several organizations, BIMP first uses your active BIMP organization when the same repository is available more than once.

Pass organization_id when you need to select an organization explicitly. BIMP searches only organizations available to the authenticated identity.

Verify the connection

Ask the client to check a real repository artifact:

Check the base images in Dockerfile against BIMP policy for
acme/payments on the main branch. Use the current file content.

Confirm that the client calls a BIMP tool and reports the organization, repository context, policy result, and any approved target. A response based only on model knowledge does not confirm a working BIMP connection.

Troubleshoot the connection

The client receives 401 Unauthorized

Run the client’s BIMP login flow again. Confirm that the endpoint host matches the environment where you authorized the client. Disabling the OAuth client or revoking its refresh family requires a new authorization.

No organization is available

Confirm that the signed-in user belongs to an organization and can read its policy or organization context. An empty, deleted, or malformed custom role does not inherit member permissions.

The tool cannot find the repository

Use the provider-qualified repository full name, a tracked branch, and the repository-relative file path. Confirm that your identity can access that repository in BIMP.

The result describes stale source

Pass the current local file_content. Scanned state is a fallback when current content is unavailable, not a reason to ignore an unsaved edit.