Connect Amazon Q Developer CLI to StackJack

The Amazon Q Developer CLI connects to remote MCP servers (MCP is the Model Context Protocol, the open standard AI tools use to call external tools). Remote MCP with OAuth sign-in has been supported since September 2025 — a recent build can sign in with just the URL.

Prerequisites

• A recent Amazon Q Developer CLI build. Older builds have known Streamable-HTTP and OAuth-discovery bugs (some issues remain open upstream) — update the CLI first if sign-in fails.
• A StackJack account that is a member of your workspace. Any team member can connect — no admin-created credentials needed for the sign-in path.
• Your StackJack MCP endpoint URL: https://mcp.stackjack.io/mcp.

Connect with sign-in (recommended)

1. Add StackJack to ~/.aws/amazonq/mcp.json (global) or .amazonq/mcp.json (workspace) with only the URL:

   {
     "mcpServers": {
       "stackjack": {
         "type": "http",
         "url": "https://mcp.stackjack.io/mcp"
       }
     }
   }
   

2. Run /mcp inside the Q CLI. It prints a sign-in URL for StackJack — open it in your browser and sign in with the same email, password, and MFA you use for the StackJack Portal.

Where config lives now: newer Q CLI versions moved primary MCP configuration into agent files under ~/.aws/amazonq/cli-agents/*.json. The legacy mcp.json paths above are still loaded (via the agent's useLegacyMcpJson behavior), so they remain the simplest cross-version option; if you manage custom agents, you can put the same server entry in your agent file instead.

Manual credentials (fallback)

If sign-in still fails after updating (upstream OAuth bugs — including missing token refresh in some builds — are tracked publicly), use a static header. An owner, co-owner, or Administrator creates an MCP client in the portal (see Managing MCP credentials). Base64-encode CLIENT_ID:CLIENT_SECRET (echo -n "CLIENT_ID:CLIENT_SECRET" | base64) and add a headers block to the same mcp.json:

{
  "mcpServers": {
    "stackjack": {
      "type": "http",
      "url": "https://mcp.stackjack.io/mcp",
      "headers": {
        "Authorization": "Basic <BASE64_OF_CLIENT_ID:CLIENT_SECRET>"
      },
      "timeout": 120000
    }
  }
}

Tool limits

Amazon Q does not publish a hard MCP tool cap, but StackJack can expose hundreds of tools depending on your connectors and plan. Connect through a client with a restricted tool selection to keep the menu focused, or switch StackJack to compact catalog mode so it serves a small tool list and Q discovers the rest on demand. An admin must first enable catalog modes for your organization on Endpoints; until then StackJack serves the full tool list. See Choosing tools for each client and managing harness tool limits.

Troubleshooting

• Sign-in URL never appears, or discovery errors — update the Q CLI to the latest build; these are known bugs in older versions.
• Connection works, then fails an hour later — some Q CLI builds do not refresh OAuth tokens; update the CLI or switch to the manual-credentials fallback.
• Sign-in says no account was found — sign up in the portal first, or ask your team admin for an invite.
• For anything else, see Connection troubleshooting.