MCP integration

BIMP exposes a remote Model Context Protocol endpoint so compatible assistants can check container images and prepare remediation plans against live published policy. The assistant does not need to guess which image your organization has approved, which is an excellent category of guessing to retire.

MCP tools are advisory and non-policy-mutating. They do not publish policy, change BIMP configuration, or edit a repository by themselves.

Prerequisites

You need:

• access to a BIMP environment where MCP is included and enabled;
• membership in at least one organization with permission to read policy or organization context;
• a compatible MCP client with remote HTTP and OAuth support; and
• repository name, branch, and file path context for useful results.

Find the endpoint

In BIMP, open Settings → Automation → MCP. The page shows the endpoint for the current environment:

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

Use the value displayed by BIMP rather than copying an endpoint from another environment. OAuth tokens are audience-bound to the resource you connect.

Connect Codex

The MCP settings page provides the commands with the correct host. Their shape is:

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

The login command opens the BIMP OAuth authorization flow. Review the requested access, sign in, and approve the client. BIMP uses OAuth 2.1 authorization code flow with S256 PKCE. Access tokens are short-lived, resource-bound JWTs; refresh and client revocation are managed by the authorization server.

Connect another MCP client

For clients that accept MCP JSON, start with:

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

The endpoint advertises protected-resource and authorization-server metadata. A compatible client should discover the authorization flow rather than asking you to paste an access token into configuration.

Available tools

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.

Provide the repository full name, branch, and file path. Also provide current file content when it is available; BIMP prefers that content over previously scanned state. You can optionally supply a specific image and OCI 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.

The result is a plan. Your assistant should still show the proposed edit and follow the repository’s normal review process.

Choose the organization

If your account can access one organization, BIMP can resolve that context. If you can access several, pass organization_id when the client or prompt needs to avoid ambiguity. BIMP only searches 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 is not a successful BIMP check.

Troubleshooting

The client receives 401 Unauthorized

Run the client’s BIMP login flow again. Confirm that the endpoint host matches the environment where you authorised 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 not available, not a reason to ignore an unsaved edit.