Skip to main content
Instead of using stdio, you can run the server as a persistent HTTP service. This enables multi-user scenarios and remote deployment.

Transport Types

Stateless Mode

For Kubernetes deployments or environments where session state should be ephemeral, use the --stateless flag with streamable-http transport:
The --stateless flag is only supported with streamable-http transport. Using it with stdio or sse will result in an error.

Basic Setup

IDE Configuration:

TLS (HTTPS Listener)

By default the HTTP transports listen in plaintext, and TLS is typically terminated by a reverse proxy or ingress in front of the server. For end-to-end TLS — for example when policy requires encryption all the way to the pod — the server can terminate TLS itself. Provide a certificate and private key (PEM) and the listener switches to HTTPS:
CLI flags override the environment variables, mirroring host/port precedence.
The HTTPS listener requires MCP_ATLASSIAN_USE_SYSTEM_TRUSTSTORE=false. The OS trust store injection (on by default) replaces Python’s ssl.SSLContext with a client-side-only implementation that rejects every inbound TLS handshake, so startup aborts if both are enabled. Set it as a real environment variable or in the default .env file — --env-file is loaded too late to affect trust store injection.With the injection disabled, outbound SSL verification uses the bundled certifi CAs. If your Atlassian instance uses a private CA, point both REQUESTS_CA_BUNDLE (covers the Jira/Confluence REST clients and OAuth token exchange, via requests) and SSL_CERT_FILE (covers the OAuth proxy paths, via httpx) at your CA bundle; the bundle must also include public roots if you talk to Atlassian Cloud. Do not work around certificate errors with JIRA_SSL_VERIFY=false / CONFLUENCE_SSL_VERIFY=false — that disables verification on the channel carrying every user’s credentials.
Remember to update client configuration to https:// URLs once the listener serves TLS — the examples elsewhere on this page use http://.
Certificate and key must be provided together — setting only one aborts startup. These options configure the server’s own listener certificate; they are unrelated to the client-side *_CLIENT_CERT mTLS options used when connecting to Atlassian. The key must be unencrypted, and the certificate is loaded once at startup — rotation requires a restart. Under stdio there is no network listener, so the options are ignored with a warning.

Host and Origin checks

When header-less requests are served with the operator’s global credentials (ALLOW_GLOBAL_CRED_FALLBACK=true or IGNORE_HEADER_AUTH=true), the server checks two headers. A request with an Origin header gets 403 unless the origin is on this machine (localhost, 127.0.0.1, [::1]) or listed in FASTMCP_HTTP_ALLOWED_ORIGINS, whatever address it arrives on. Requests without Origin, such as MCP clients and proxies, pass. A request that arrives on a loopback address also gets 421 unless its Host is local. This stops a web page in a browser from acting with the credentials the listener holds. Other deployments keep FastMCP’s default, which does not check these headers. A reverse proxy on the same host that forwards to 127.0.0.1 and passes the public hostname in Host needs that hostname in FASTMCP_HTTP_ALLOWED_HOSTS.

Server-side file paths

Some tools accept a path on the server’s filesystem: confluence_upload_attachment(s) and jira_update_issue (attachments) read a file and upload it, and confluence_create_page / confluence_update_page read content_file. Over HTTP the caller is remote, so these paths are confined to one directory:
  • MCP_ATLASSIAN_FILES_DIR when set.
  • Otherwise ~/.mcp-atlassian/files for the user running the server (created on start). The process working directory is not used on sse / streamable-http, because it depends on how the server was started (/ for a systemd system unit, $HOME for a user unit or a shell).
The server refuses to start on a remote transport if MCP_ATLASSIAN_FILES_DIR is a filesystem root or a home directory. Put only files you intend callers to upload in this directory. In multi-user deployments every caller shares it, so prefer the base64 content inputs and leave the directory empty when you can. On stdio (a local client) the boundary stays the working directory unless MCP_ATLASSIAN_FILES_DIR is set, so existing local setups keep working.

systemd

Set both the working directory and the files directory explicitly. Without WorkingDirectory=, a system unit starts in / (see systemd.exec(5)).
Keep secrets such as .env files outside both directories.

Docker

The official image works from /app. To upload files from the host, mount a dedicated directory and point the variable at it:

Multi-User Authentication

Both transport types support per-request authentication where each user provides their own credentials.

Authentication Methods

Restrict Request-Supplied URLs

Over HTTP, clients can name their own instance with the X-Atlassian-Jira-Url / X-Atlassian-Confluence-Url headers (header-based PAT). Set MCP_ALLOWED_URL_DOMAINS to the domains your users connect to:
Without it, any public host is accepted and the server logs a warning at startup. The allowlist will be required for HTTP transports with header-based URLs in v0.25.

Server Setup for Multi-User

1

Run OAuth Setup (if using OAuth)

2

Start HTTP Server

3

Configure Environment

OAuth Discovery + DCR for MCP Clients

When ATLASSIAN_OAUTH_PROXY_ENABLE=true, the HTTP service exposes OAuth discovery and DCR endpoints so MCP clients can onboard users through spec-aligned OAuth:
  • /.well-known/oauth-protected-resource
  • /.well-known/oauth-authorization-server
  • POST /register
  • GET /authorize
  • POST /token
  • callback route derived from ATLASSIAN_OAUTH_REDIRECT_URI
Use this for remote clients like ChatGPT/Codex that expect discovery + DCR.
The DCR client’s redirect_uri must be different from the OAuth proxy’s own IdP callback. If a client tries to register the proxy callback as its redirect URI, registration is rejected with invalid_redirect_uri to prevent a callback loop.

Multi-Cloud Support

For multi-tenant applications where each user connects to their own Atlassian cloud instance:
  1. Enable minimal OAuth mode:
  2. Users provide authentication via HTTP headers:
    • Authorization: Bearer <user_oauth_token>
    • X-Atlassian-Cloud-Id: <user_cloud_id>

Python Example

  • Requests without user-specific credentials are rejected unless ALLOW_GLOBAL_CRED_FALLBACK=true
  • User tokens are isolated per request - no cross-tenant data leakage
  • Falls back to global ATLASSIAN_OAUTH_CLOUD_ID if header not provided