Documentation

Overview

Foxbridge is a self-hosted AI assistant for Atlassian. It connects to Jira, Confluence, and Bitbucket through a web chat interface and an MCP endpoint for IDE integration. You choose the AI provider, and all data stays on your infrastructure.

Foxbridge runs as a Docker container exposing two ports:

• Port 3000 — Web chat UI (browser-based interface)
• Port 3001 — MCP transport (for Claude Code, VS Code, Cursor, and other MCP clients)

---

Complete Config Reference

Foxbridge is configured via a foxbridge.yaml file mounted into the Docker container. Here is every available option with defaults:

license_key: "FK-XXXXXXXX-XXXXXXXX-XXXXXXXX"

atlassian:
  platform: "cloud"                    # "cloud" or "datacenter"
  base_url: "https://yourorg.atlassian.net"
  auth_method: "pat"                   # "basic" or "pat"
  jira_url: ""                         # optional: override for Jira
  confluence_url: ""                   # optional: override for Confluence
  bitbucket_url: ""                    # optional: override for Bitbucket

ai:
  provider: "anthropic"                # "anthropic", "openai", "azure_openai", or "ollama"
  api_key: "sk-ant-..."               # API key (not needed for Ollama)
  model: ""                            # optional: override default model
  base_url: ""                         # required for azure_openai and ollama

features:
  jira:
    read: true
    write: false
  confluence:
    read: true
    write: false
  bitbucket:
    read: true
    write: false
  assets:
    read: false
    write: false

oauth:                                 # optional: for "Sign in with Atlassian" button
  client_id: ""
  client_secret: ""
  callback_url: "http://localhost:3000/api/auth/callback"

scrub_pii: false                       # redact PII before sending to AI
dev_mode: false                        # bypass license check (development only)
log_level: "info"                      # "debug", "info", "warn", or "error"
port_chat: 3000                        # web chat UI port
port_mcp: 3001                         # MCP transport port

All options explained

---

Atlassian Platform Support

Jira Cloud

Set platform: "cloud" and base_url to your Atlassian Cloud URL (e.g., https://yourorg.atlassian.net). Three authentication options:

• OAuth 2.1 — "Sign in with Atlassian" button. Best UX, one-click login. Requires OAuth app setup (see OAuth Setup).
• Basic auth (auth_method: "basic") — user enters their Atlassian email + API token at login.
• PAT (auth_method: "pat") — user enters a Personal Access Token at login.

Jira Data Center

Set platform: "datacenter" and base_url to your server URL (e.g., https://jira.yourcompany.com). Two authentication options:

• Basic auth (auth_method: "basic") — user enters their username + password at login.
• PAT (auth_method: "pat") — user enters a Personal Access Token. More secure, recommended.

If your Jira, Confluence, and Bitbucket run on different servers, set each URL individually using jira_url, confluence_url, and bitbucket_url. If they share one URL, only base_url is needed.

Foxbridge uses REST API v2 for Data Center and REST API v3 for Cloud. The platform setting ensures the correct API version is used automatically.

---

AI Providers

Anthropic Claude

ai:
  provider: "anthropic"
  api_key: "sk-ant-api03-..."
  model: "claude-sonnet-4-20250514"    # optional, defaults to latest Sonnet

Best for tool use. Vision (image analysis) is supported with Anthropic. Get an API key at console.anthropic.com.

OpenAI

ai:
  provider: "openai"
  api_key: "sk-..."
  model: "gpt-4o"                      # optional

Supports GPT-4o, GPT-4, and other OpenAI models. Get an API key at platform.openai.com.

Azure OpenAI

ai:
  provider: "azure_openai"
  api_key: "your-azure-key"
  base_url: "https://your-resource.openai.azure.com"
  model: "your-deployment-name"        # deployment name, not model name

For organizations using Azure's OpenAI Service. The model must be your deployment name, not the model name. The base_url is your Azure resource endpoint.

Ollama (Local / Air-Gapped)

ai:
  provider: "ollama"
  base_url: "http://host.docker.internal:11434"
  model: "llama3.1"                    # any model you've pulled

No API key needed. Data never leaves your network. Install Ollama and pull a model (ollama pull llama3.1). The host.docker.internal hostname lets the Docker container reach Ollama on your host machine.

---

Available Tools (40+)

Jira (17 read + 11 write)

Read: Search issues (JQL), read issue details, comments, transitions, boards, sprints, sprint issues, projects, fields, priorities, statuses, attachments, worklogs, issue types, users.

Write: Create/update/delete issues, add/update/delete comments, transition workflows, assign issues, link issues, add attachments, log work.

Confluence (7 read + 5 write)

Read: Search content (CQL), read pages and blog posts, list spaces, get page children and attachments.

Write: Create/update pages, add attachments.

Bitbucket (8 read + 2 write)

Read: List repositories, branches, pull requests, commits, read file contents, diffs, PR comments.

Write: Create branches, add PR comments.

Write tools are disabled by default. Enable them per-product in the features section of foxbridge.yaml. The AI always shows a preview and asks for confirmation before executing bulk operations.

---

File Upload

Users can drag-and-drop or attach files in the chat for AI analysis or attachment to Atlassian items:

• Supported formats: CSV, XLSX, PDF, DOCX, PPTX, PNG, JPG, plain text, Markdown
• Max size: 25 MB per file, 5 files per message
• Use cases:

• "Turn this spreadsheet into Jira tickets" — parses CSV/XLSX, creates one ticket per row
• "Summarize this PDF" — extracts text and provides a summary
• "Attach this to PROJ-123" — uploads the file to a Jira issue
• "What's in this screenshot?" — image analysis (Anthropic only)

---

PII Scrubbing

Enable scrub_pii: true to automatically detect and redact personally identifiable information before it's sent to the AI provider. Detected patterns include:

• Email addresses
• Phone numbers
• Names (based on common patterns)

Recommended for healthcare, finance, government, and any deployment where ticket data may contain sensitive personal information. PII scrubbing happens in-memory before data leaves Foxbridge — your AI provider never sees the original PII.

---

OAuth Setup (optional)

OAuth enables the "Sign in with Atlassian" button — one-click login instead of manual API token entry. This is optional; API token login always works as a fallback.

1. Register an OAuth 2.1 app at developer.atlassian.com
2. Set the callback URL to http://your-foxbridge-host:3000/api/auth/callback
3. Request scopes: read:jira-work, write:jira-work, read:confluence-content.all, etc.
4. Add the client ID, secret, and callback URL to foxbridge.yaml

OAuth is Cloud-only. Data Center uses PAT or basic auth.

---

Licensing

Foxbridge requires a license key to start. The key is validated on startup and revalidated every 6 hours. If the validation server is unreachable, a 72-hour grace period allows continued operation.

• Trial: 14 days, 10 concurrent users — get a trial key
• Team: 25 concurrent users
• Business: 100 concurrent users
• Enterprise: Unlimited users

Concurrent users = active sessions at the same time. When a user closes their browser, the session expires after 8 hours and frees a seat.

---

MCP / IDE Integration

Foxbridge exposes an MCP (Model Context Protocol) endpoint on port 3001. This lets you use Foxbridge tools from Claude Code, VS Code, Cursor, or any MCP-compatible client.

The MCP endpoint supports the same tools as the web chat — search Jira issues, read Confluence pages, etc. — directly from your IDE.

See the setup guide for configuration instructions.