Add the server from the Q Developer Chat panel
Open your IDE with Q Developer installed, such as VS Code or a JetBrains IDE (Amazon Q docs). In the Q Developer Chat panel, choose the tools icon to open the MCP configuration UI (Amazon Q docs).
Add a new MCP server and select the scope: global, stored in ~/.aws/amazonq/default.json and available across all projects, or local, stored in .amazonq/default.json within the current project (Amazon Q docs). Select stdio as the transport protocol. Amazon Q supports two transports, STDIO and HTTP (Amazon Q docs).
In the Command field, which takes the shell command the server runs when it initializes, enter npx (Amazon Q docs). In the Arguments field, which takes command arguments, enter -y @knowman/mcp (KnowMan MCP repository). Environment variables are entered as Name and Value pairs (Amazon Q docs); add KNOWMAN_API_KEY with the value km_... (KnowMan MCP repository). Keep the timeout at the recommended 60 seconds, then choose Save (Amazon Q docs).
Sign in once with knowman login
Instead of pasting a key, run npx -p @knowman/mcp knowman login once. It opens browser sign-in, and the saved credential is shared by the CLI and the MCP server, so the environment variable entry can be dropped (KnowMan MCP repository).
An API key works too. Create one in the KnowMan web app at Settings > Connections > Connect an AI agent; keys look like km_... (KnowMan MCP repository). The server needs Node 22 or newer and starts with npx -y @knowman/mcp (KnowMan MCP repository).
Check the connection
After you add an MCP server, Amazon Q attempts to connect to it (Amazon Q docs). If there are connection issues, an alert appears in the panel, and tools from that server should not be expected to work until the alert is resolved (Amazon Q docs). Choose Fix Configuration to return to the MCP configuration screen (Amazon Q docs).
With no alert showing, ask Q something like "search my KnowMan for quarter planning" to try kb_search, or "save this URL" to try kb_save (KnowMan MCP repository).
Set permissions for each tool
When you choose Save, the tool permissions panel replaces the configuration panel (Amazon Q docs). Permissions are set per tool, and the Ask level prompts you for permission each time the tool is used (Amazon Q docs). You can pick a level for each of the six KnowMan tools (KnowMan MCP repository).
The six KnowMan tools
The server exposes six tools (KnowMan MCP repository). kb_search searches saved items by keyword or meaning and returns titles, URLs and metadata; kb_ask answers a question with citations; kb_get_item returns the readable content of one item; kb_save saves a URL to the Inbox or the Knowledge Base with an optional note; kb_recent lists recent items; and kb_memories lists saved claims, decisions and playbooks (KnowMan MCP repository).
For more on the server and its setup, see the MCP server knowledge base guide.
Where Amazon Q stores the configuration
Servers added through the GUI are stored at global scope in ~/.aws/amazonq/default.json or local scope in .amazonq/default.json (Amazon Q docs). For legacy reasons, the same configuration can also live in ~/.aws/amazonq/mcp.json or .amazonq/mcp.json; this is controlled by the useLegacyMcpJson field in the global default.json, which defaults to true (Amazon Q docs).
Q Developer gives precedence to workspace-level configurations for MCP servers, their permissions, and the stored settings (Amazon Q docs). The mcp.json files may also be used by the Q CLI (Amazon Q docs).
Disable the server
To turn the server off, open the MCP Servers panel and choose the server. Choose the three dots next to Edit setup, then choose Disable MCP Server (Amazon Q docs).
To point other clients at the same knowledge base, see connect any AI to your notes.
Questions people ask
Where does Amazon Q Developer keep MCP server settings?
Global configuration is stored in ~/.aws/amazonq/default.json, and local configuration in .amazonq/default.json within the current project (Amazon Q docs). Legacy mcp.json files are also read at both scopes, controlled by useLegacyMcpJson, which defaults to true (Amazon Q docs).
Q shows an alert after I add the server. What now?
Amazon Q attempts to connect after you add an MCP server, and connection issues appear as an alert in the panel; tools from that server should not be expected to work until the alert is resolved (Amazon Q docs). Choose Fix Configuration to return to the MCP configuration screen (Amazon Q docs).
Can I sign in without pasting an API key?
Run npx -p @knowman/mcp knowman login once (KnowMan MCP repository). It opens browser sign-in, and the saved credential is shared by the CLI and the MCP server, so the environment variable entry can be dropped (KnowMan MCP repository).
How do I disable the server?
Open the MCP Servers panel and choose the server (Amazon Q docs). Choose the three dots next to Edit setup, then choose Disable MCP Server (Amazon Q docs).