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.

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 either OAuth or custom request headers; 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.

Choose an authentication method

Use OAuth for a human connection. It follows the signed-in user’s organization memberships and does not require the Automation API feature.

Use an API key for unattended automation. API-key MCP connections require the organization’s edition or active grant to include Automation API, and they are restricted to the key’s owning organization, service-account access, and any key attenuation rules.

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 Codex with an API key

Create an organization API key under Settings → Automation → API keys and store the secret in your secret manager. Expose it to Codex as BIMP_API_KEY, then configure the header without copying the secret into the configuration file:

[mcp_servers.bimp]
url = "https://<your-bimp-host>/api/v1/mcp"
env_http_headers = { "x-api-key" = "BIMP_API_KEY" }

If this server still has stored OAuth credentials, x-api-key takes precedence. Remove the header configuration to return to OAuth.

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.

For API-key authentication, configure the client to source this header from a secret store or environment variable:

x-api-key: <api-key-secret>

Header secret interpolation differs between clients. Do not commit the API key in MCP JSON or another client configuration file.

After connecting, see Use BIMP with your coding agent for repository instructions, common workflows, example tasks, and recurring image reviews.

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. An API-key connection always uses the key’s owning organization, and an organization_id for any other organization is rejected.

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

For OAuth, run the client’s BIMP login flow again and 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.

For an API key, confirm that x-api-key is populated from the expected secret, the key is active and bound to an enabled automation identity, and the owning organization includes Automation API. BIMP returns the same generic challenge for rejected credentials and does not disclose which check failed.

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.