Claude: Advanced agentic configuration

By default, Agentic Pipelines uses a system-provided Claude Agent configuration that is suitable for simple use cases. For more advanced scenarios, you can:

provide your own claude-config-overrides.json
override configuration fields directly from bitbucket-pipelines.yml
add additional MCP servers
plug-in an Atlassian MCP server by providing a user API token

This page explains the configuration options listed above.

Limitations for background tasks

Claude supports starting a task in the background and notifying the main agent when the task is complete. Agentic Pipelines will treat this as a full-round of execution if the main agent has no other tasks to do and is in ‘awaiting next instruction’ mode. This might impact the following:

Agent Team, which creates subagents in the background
Schedule Wakeup, CronCreate, and \loop, which wakes up the main agent using one-shot delay or scheduled cron tasks.
Other tools with run_in_background capability. An example is the bash tool can be called in the background, which is not recommended to be used within agentic pipelines.

Claude CLI requirements

The Claude CLI requires libgcc,libstdc++ and ripgrep in the build image. The default image atlassian/default-image:5 already meets this requirement, and all major Linux-based Docker images are compatible.

Alpine Linux is supported but requires a few extra packages. Run the following command to add all required packages. See Advanced setup - Claude Docs.

apk add libgcc libstdc++ ripgrep

Provide your own custom Claude config file

You can supply your own Claude configuration and have Pipelines merge it with the system base config.

Note: By default, Claude will auto-detect .claude/settings.json in your repository, and it will be used as project-level settings. Any other files will be treated as local settings, with a higher priority. See Claude settings for more information on its structure.

You can store the config:

in your repository (for example .claude/some-config.json)
included in the build image
generated earlier in the step script

The config file at config.path is merged with the Pipelines system config. See Agentic Pipelines - System defaults for details on what is configured for you.

Example `settings.json`

{
  "model": "haiku",
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": 60000
  },
  "permissions": {
    "allow": [
      "Bash(curl *)"
    ],
    "deny": [
      "Bash(npm run lint)"
    ]
  }
}

Use configuration overrides in bitbucket-pipelines.yml

Instead of, or in addition to, a config file, you can define config.overrides directly in your pipeline YAML. Overrides can be provided by a Dynamic Pipelines Provider to enforce specific agentic configuration.

Structure

These can be specified on both the agent and step level.

overrides use the same object structure as the Claude settings schema, but as a YAML object.

Merge order

Configurations are merged in this order (later wins):

Pipeline system base config
User config from config.path (JSON)
User config from config.overrides (YAML)
System‑enforced overrides (for example, Bitbucket MCP injection)

Within a given config level:

Maps are merged by key
Lists are overwritten

Example of bitbucket-pipelines.yml

definitions:
 agents:
    my-agent:
      prompt: Explain this repository
      provider: claude
pipelines:
  default:
    - step:
        script:
          - agent: my-agent
            config:
              overrides:
                model: opus[1m]
                env:
                  DISABLE_PROMPT_CACHING: 1
                permissions:
                  allow:
                    - "Bash(npm run lint)"
                  deny:
                    - "Bash(curl *)" 

Example of .claude/settings.json

{
  "model": "haiku",
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": 60000
  },
  "permissions": {
    "allow": [
      "Bash(curl *)"
    ],
    "deny": [
      "Bash(npm run lint)"
    ]
  }
}

Merged configuration

model from YAML wins
env is merged
allow and deny lists are replaced, YAML wins

{
  "model": "opus[1m]",
  "env": {
    "DISABLE_PROMPT_CACHING": 1,
    "BASH_DEFAULT_TIMEOUT_MS": 60000
  },
  "permissions": {
    "allow": [
      "Bash(npm run lint)"
    ],
    "deny": [
      "Bash(curl *)"
    ]
  }
}

Defining ask modes

You can use permissions to selectively allow or deny tools. The default mode is denyOnAsk, so you must explicitly allow tools that are required for the task.

However, in some cases, managed settings from your organization may override allowed tools to ask mode, which does not work in a CI environment as no user input can be provided.

As a workaround we added an on-ask: allow property on the agent that will answer yes to all undefined/overridden permissions.

Allow on ask

definitions:
  agents:
    my-agent:
      provider: claude
      prompt: "Generate an activity report on this repository and post it in Slack."
      permissions:
        on-ask: allow
pipelines:
  default:
    - step:
        script:
          - agent: my-agent

Add an extra MCP server

In addition to providing the Bitbucket MCP server, Rovo Dev CLI allows configuration of third-party MCP servers. This allows you to extend the capabilities of your AI agent.

For more details, look at the Rovo Dev CLI documentation: Connect to an MCP server in Rovo Dev CLI.

1. Register your MCP server in `.mcp.json`

Note: This must be in your project’s root directory for it to be picked up by Claude.

Example

{
  "mcpServers": {
    "my-stdio-server": {
      "type": "stdio",
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    },
    "my-stdio-docker-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "my-docker-mcp"]
    },
    "my-http-server": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${YOUR_API_KEY}"
      }
    }
  }
}

Supported transports

MCP supports two transport methods:

stdio: Communication via standard input/output (most common)
http: Communication via HTTP requests

2. No special configuration in your pipeline

Example

definitions:
  agents:
    my-agent:
      prompt: "Do something using my extra MCP tools"
      config:
        path: .claude/config.json
pipelines:
  default:
    - step:
        script:
          - agent: my-agent

Configuring Atlassian MCP (Jira, Confluence, etc.)

For Claude and Codex agents, add a scoped API token to a user-defined variable named ATLASSIAN_MCP_API_TOKEN. The token’s scopes determine which operations the agent can perform.

To create a token:

Create a personal API token with the required scopes.
If necessary, select Back to choose the scopes you want your API token to have.

ATLASSIAN_MCP_API_TOKEN is only used to authenticate requests to Atlassian products like Jira and Confluence. Bitbucket operations do not use this token; they automatically authenticate using the pipeline step's repository-scoped OAuth token and the scopes defined in your bitbucket-pipelines.yml file.

Controlling MCP tool execution

Configure the agent to request permission for the tools you want Pipelines to control, then use permissions.on-ask in your pipeline configuration to approve or deny those requests automatically.

These rules apply only to permission requests received by Pipelines. Tools already approved or blocked by the agent’s own configuration may not produce a request.

See Agent configuration for rule syntax, matching, precedence and inheritance.

Was this helpful?

It wasn't accurateIt wasn't clearIt wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community