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). StackJack's setup wizard places Amazon Q in Paste a credential, so the first-run path below uses a generated MCP client credential. Recent Q builds also support URL-only OAuth as a supported alternative.

Prerequisites

• An MCP client credential created on MCP Setup by an owner, co-owner, or Administrator.
• A recent Amazon Q Developer CLI build if you want to use the OAuth alternative. Older builds have known Streamable-HTTP and OAuth-discovery bugs.
• Your StackJack MCP endpoint URL. Copy it from the MCP Setup page in the portal — that card shows the address for your workspace's region. The examples in this guide use the US address, https://mcp.stackjack.io/mcp; other regions have their own hostname. See Your region and your endpoint.

StackJack setup-wizard path: generated credential

Before you paste a credential anywhere, three things about it.

• Base64 is encoding, not encryption. Anyone who can read the encoded string can decode it back to the client id and secret in one command. Treat the encoded value as the secret itself.
• A typed command lands in your shell history. Produce the encoding in a way that keeps the secret out of that file, or clear the entry afterwards.
• A config file inside a repository gets committed and shared. Keep credential-bearing config on your own machine, outside any repository. Where the client offers a secret prompt or a protected credential store, use it — the client's own documentation is what governs which of those it supports. For an automated environment, take the value from that platform's secret store rather than writing it into a file.

1. Base64-encode CLIENT_ID:CLIENT_SECRET (echo -n "CLIENT_ID:CLIENT_SECRET" | base64).

2. Add StackJack to ~/.aws/amazonq/mcp.json (global) or .amazonq/mcp.json (workspace) with the generated credential in an Authorization header:

   Copy code

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

3. Run /mcp inside the Q CLI and confirm the StackJack server connects.

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.

Supported alternative: URL-only OAuth

Recent Amazon Q builds can also connect with only the URL. This is supported, but it is not the first-run lane StackJack's setup wizard shows for Amazon Q. Remove the headers block so the entry contains only:

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

Run /mcp. Q prints a StackJack sign-in URL; open it in your browser and sign in with your normal StackJack account. If OAuth discovery or token refresh is unreliable in your Q build, return to the generated-credential path above.

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 the Settings page; 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 on the OAuth alternative — some Q CLI builds do not refresh OAuth tokens; update the CLI or switch to the generated-credential path.
• 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.