Merge pull request #136 from speakeasy-api/guide/issue-135-atlassian

guide: Atlassian

Author: svadrutk

guides/atlassian/external.md

@@ -0,0 +1,55 @@
+---
+setup_version: 1
+---
+
+# Set up Atlassian Rovo
+
+You need an Atlassian Cloud site with Jira, Confluence, and/or Compass, and the connecting Atlassian account must have access to the intended site and apps. Use a modern browser. Atlassian documents no paid-plan requirement for the MCP Server.
+
+You need no Atlassian-side configuration unless your organization restricts OAuth client domains, IP addresses, third-party apps, or network egress. For OAuth-domain or IP-allowlist restrictions, sign in to Atlassian Administration with an organization-admin account and complete the applicable checks below. If **User Installed Apps** is blocked, ask a site admin for help. For strict egress filtering, ask your network/security owner to allow the required Atlassian domain.
+
+### Allow the Speakeasy OAuth domain {#allow-speakeasy-domain}
+
+1. Open [admin.atlassian.com](https://admin.atlassian.com/).
+2. If more than one organization is shown, select the organization you want to connect.
+3. Select **Rovo**.
+4. Select **Rovo MCP server**.
+5. Check whether the allowed domains cover this hosted OAuth callback:
+
+   ```
+   https://app.getgram.ai/mcp/remote_login_callback
+   ```
+
+6. If it is not covered, select **Add domain**.
+7. Enter this exact custom domain pattern:
+
+   ```
+   https://app.getgram.ai/mcp/remote_login_callback
+   ```
+
+8. Use the submission control shown in the console.
+
+Keep **Allow Atlassian supported domains** selected. Deselecting it blocks Atlassian's supported-domain set.
+
+If your organization uses IP allowlists:
+
+1. Ask your network/security owner whether hosted Speakeasy traffic has stable outbound IP addresses or CIDR blocks that your organization can allow. Do not guess these ranges.
+2. If your network/security owner supplies ranges, return to your organization in [admin.atlassian.com](https://admin.atlassian.com/).
+3. Select **Security**.
+4. Select **IP allowlists**.
+5. Open the applicable allowlist, or select **Create IP allowlist**.
+6. Enter a name and the source IP addresses or CIDR blocks in the fields shown.
+7. Select the Atlassian sites and apps to which the allowlist applies.
+8. Use the submission control shown in the console.
+
+If your organization uses strict egress filtering, ask your network/security owner to allow the following domain in your organization's network controls so interactive Jira and Confluence widgets can render:
+
+```
+*.atlassian.net
+```
+
+<!-- screenshot: Rovo > Rovo MCP server showing the domain list and Add domain, with organization-specific domains redacted; a separate image could show the relevant organization IP-allowlist policy without exposing unrelated ranges -->
+
+If Atlassian denies the OAuth redirect during connection, return to **Rovo** > **Rovo MCP server** and verify that the client origin matches an allowed domain or pattern. If the authorization screen appears but a tool call returns an IP permission error, update the relevant organization IP allowlist.
+
+If authorization reports that the app must be installed because **User Installed Apps** is blocked, ask a site admin to install the Atlassian MCP app under the organization's Marketplace and third-party app policy.

guides/atlassian/meta.yaml

@@ -0,0 +1,127 @@
+# yaml-language-server: $schema=../../schema/guide.v1.schema.json
+schema_version: 1
+slug: atlassian
+title: Atlassian Rovo
+summary: Connect Atlassian Rovo so users can access their permitted Jira, Confluence, and Compass work through the hosted MCP server.
+speakeasy_add_server: auto
+credential_setup:
+  options:
+    - id: oauth-dcr
+      kind: oauth
+      client_registration: dynamic
+      upstream_setup: provider-steps
+  requirements:
+    - id: atlassian-cloud-site
+      description: Atlassian Cloud site with Jira, Confluence, and/or Compass
+    - id: product-access
+      description: Atlassian account with access to the intended Cloud site and products
+    - id: organization-policy-approval
+      description: Administrative action when OAuth domains, IP allowlists, or User Installed Apps policy restrict the connection
+documentation:
+  external: external.md
+  speakeasy: speakeasy.md
+remotes:
+  - id: rovo
+    url: https://mcp.atlassian.com/v1/mcp/authv2
+    transport: streamable-http
+    authentication:
+      - oauth-dcr
+    provenance:
+      - source: provider-documentation
+        locator: https://support.atlassian.com/atlassian-rovo-mcp-server/docs/getting-started-with-the-atlassian-remote-mcp-server/
+        name: Getting started with the Atlassian Rovo MCP Server
+        classification: official
+        observed_at: "2026-08-07T19:24:55Z"
+      - source: endpoint-observation
+        locator: https://mcp.atlassian.com/v1/mcp/authv2
+        classification: official
+        observed_at: "2026-08-07T19:24:55Z"
+      - source: endpoint-observation
+        locator: https://mcp.atlassian.com/.well-known/oauth-protected-resource/v1/mcp/authv2
+        classification: official
+        observed_at: "2026-08-07T19:24:55Z"
+provenance:
+  - source: pulsemcp
+    locator: query:atlassian
+    name: No exact current Atlassian Rovo title/name match
+    classification: mirror
+    status: ambiguous; deprecated old external-protocol entry excluded
+    observed_at: "2026-08-07T19:24:55Z"
+  - source: workflow-operator-notes
+    locator: assignment:atlassian
+    name: Speakeasy callback and catalog-path observations
+    classification: official
+    status: hosted callback confirmed; hosted outbound IP ranges unknown
+    observed_at: "2026-08-07T19:24:55Z"
+  - source: provider-documentation
+    locator: https://support.atlassian.com/atlassian-rovo-mcp-server/docs/getting-started-with-the-atlassian-remote-mcp-server/
+    name: Getting started with the Atlassian Rovo MCP Server
+    classification: official
+    observed_at: "2026-08-07T19:24:55Z"
+  - source: provider-documentation
+    locator: https://support.atlassian.com/atlassian-rovo-mcp-server/docs/setting-up-clients/
+    name: Setting up clients
+    classification: official
+    observed_at: "2026-08-07T19:24:55Z"
+  - source: provider-documentation
+    locator: https://support.atlassian.com/atlassian-rovo-mcp-server/docs/authentication-and-authorization/
+    name: Authentication and authorization
+    classification: official
+    observed_at: "2026-08-07T19:24:55Z"
+  - source: provider-documentation
+    locator: https://support.atlassian.com/atlassian-rovo-mcp-server/docs/configuring-oauth-2-1/
+    name: Configuring OAuth 2.1
+    classification: official
+    observed_at: "2026-08-07T19:24:55Z"
+  - source: provider-documentation
+    locator: https://support.atlassian.com/atlassian-rovo-mcp-server/docs/configuring-authentication-via-api-token/
+    name: Configuring authentication via API token
+    classification: official
+    observed_at: "2026-08-07T19:24:55Z"
+  - source: provider-documentation
+    locator: https://support.atlassian.com/atlassian-rovo-mcp-server/docs/using-with-other-supported-mcp-clients/
+    name: Using with other supported MCP clients
+    classification: official
+    observed_at: "2026-08-07T19:24:55Z"
+  - source: provider-documentation
+    locator: https://support.atlassian.com/security-and-access-policies/docs/control-atlassian-rovo-mcp-server-settings/
+    name: Control Atlassian Rovo MCP server settings
+    classification: official
+    observed_at: "2026-08-07T19:24:55Z"
+  - source: provider-documentation
+    locator: https://support.atlassian.com/security-and-access-policies/docs/specify-ip-addresses-for-product-access/
+    name: Specify IP addresses for product access
+    classification: official
+    observed_at: "2026-08-07T19:24:55Z"
+  - source: provider-documentation
+    locator: https://support.atlassian.com/security-and-access-policies/docs/available-atlassian-rovo-mcp-server-domains/
+    name: Available Atlassian Rovo MCP server domains
+    classification: official
+    observed_at: "2026-08-07T19:24:55Z"
+  - source: provider-documentation
+    locator: https://support.atlassian.com/atlassian-rovo-mcp-server/docs/troubleshooting-and-verifying-your-setup/
+    name: Troubleshooting and verifying your setup
+    classification: official
+    observed_at: "2026-08-07T19:24:55Z"
+  - source: provider-marketing
+    locator: https://www.atlassian.com/platform/remote-mcp-server
+    name: Atlassian Rovo MCP server
+    classification: official
+    observed_at: "2026-08-07T19:24:55Z"
+  - source: endpoint-observation
+    locator: https://mcp.atlassian.com/v1/mcp/authv2
+    classification: official
+    observed_at: "2026-08-07T19:24:55Z"
+  - source: endpoint-observation
+    locator: https://mcp.atlassian.com/.well-known/oauth-protected-resource/v1/mcp/authv2
+    classification: official
+    observed_at: "2026-08-07T19:24:55Z"
+  - source: endpoint-observation
+    locator: https://auth.atlassian.com/VCeDsk8ZHncYF1g234fKtc4lNipbBhu3/.well-known/oauth-authorization-server
+    classification: official
+    observed_at: "2026-08-07T19:24:55Z"
+  - source: repository-doctrine
+    locator: doctrine/speakeasy-setup.md
+    name: Speakeasy setup canonical section
+    classification: official
+    observed_at: "2026-08-07T19:24:55Z"