Find and retrieve
Search maps available to the account, then retrieve graph data, paginated results, or count-only summaries.
Model Context Protocol
The KnowMapped MCP server exposes tools for searching, creating, and editing knowledge maps and futures wheels. It can also publish public snapshots. Every operation uses the permissions of the connected KnowMapped account.
Map tools
Clients can retrieve map data, prepare drafts, apply validated edits to concepts, relationships, and wheel branches, and publish public snapshots.
Search maps available to the account, then retrieve graph data, paginated results, or count-only summaries.
New map creation costs one generation credit and requires confirmation. Extend existing maps without a creation charge.
Set map visibility, publish edits as public snapshots, and check moderation and delivery status.
Apply validated changes to concepts, relationships, wheel branches, map details, and layouts.
Connection guide
Use a client that implements MCP Streamable HTTP and OAuth 2.0. Start with the MCP endpoint and let the client follow the protected-resource challenge to discover the authorization server. Do not hard-code authorization URLs or place KnowMapped credentials in client settings.
Configure a remote Streamable HTTP server with https://mcp.knowmapped.com/mcp. Authenticated operations use a 401 response and WWW-Authenticate challenge when authorization is required. Tool discovery may be available before sign-in.
Follow the challenge to the protected-resource metadata, resolve its authorization server, and read the authorization-server metadata. This is where the client learns the endpoints, scopes, PKCE method, and registration options.
Use a Client ID Metadata Document when supported; use Dynamic Client Registration as the compatibility fallback. The client must use token_endpoint_auth_method=none, and its redirect URI must be registered exactly.
Generate a PKCE S256 verifier and challenge, open the browser authorization request, then sign in and approve the requested map scopes. Credentials stay in the KnowMapped browser flow.
Exchange the authorization code with the verifier and resource binding, send the bearer token to https://mcp.knowmapped.com/mcp, then run MCP initialization and tools/list. Refresh the client’s tools or start a new conversation after connecting.
OpenAI clients
ChatGPT
On ChatGPT web, open Plugins, select the plus button, and choose Add custom MCP server. Enter https://mcp.knowmapped.com/mcp, choose OAuth, review the requested actions, and complete KnowMapped’s browser consent flow. Create the plugin, then select it in a new chat to use its tools.
KnowMapped Professional covers access to the KnowMapped service. ChatGPT separately controls which custom MCP actions your account or workspace can use. OpenAI currently lists full MCP support for Business and Enterprise/Edu; Pro supports read and fetch actions. ChatGPT custom MCP setup is web-only.
Check ChatGPT’s current plan and connection requirementsCodex
Register the Streamable HTTP endpoint, then run the separate login command so Codex can complete the browser-based OAuth flow and cache the resulting credentials.
codex mcp add knowmapped --url https://mcp.knowmapped.com/mcp
codex mcp login knowmapped
codex mcp listRead OpenAI’s Codex MCP guide Access and billing
Every request is limited by the connected account’s existing map access. A public link does not grant edit permission, and a client cannot bypass ownership or sharing controls.
MCP map creation requires Professional or an active Professional trial. Each successfully created map uses one generation credit. Preflight shows the cost and remaining balance; creation requires explicit confirmation. Failed validation uses no credits. Reading, editing, checking publication status, and publishing existing maps do not use creation credits.
Editing and publishing have separate permissions. Approve maps:write for content edits and maps:publish for public snapshots and visibility changes. Existing connections must request fresh consent to gain publishing access.
Connections have no scheduled refresh-credential expiry in the standard deployment. Clients renew short-lived access tokens automatically and must save each rotated refresh credential. Revocation, password changes, account restrictions, or lost refresh credentials can still require reconnecting.
Disconnect the integration from your client to remove its local connection. You can also revoke OAuth access from KnowMapped when you need to invalidate an existing authorization.
Public snapshots
Edits do not change the public snapshot. Use set_knowmapped_map_visibility for first publication; the request requires maps:publish and confirmation that you have the right to make the map public.
For an already-public map, publish_knowmapped_map replaces the public snapshot with the completed draft. KnowMapped generates its public preview and applies the same moderation, restrictions, locks, and permissions as browser publishing.
Both actions need the current expected_revision and a unique idempotency_key of 1–200 characters. After a timeout, retry with the same key and identical arguments. A changed request needs a new key. Committed results can be recovered for 30 days without repeating publication or undoing later visibility changes.
Use get_knowmapped_publication_status to check the published revision, moderation, and delivery. A saved snapshot may still be awaiting delivery, and a pending review is not a successful publication. Revision differences mean content may have changed; operational changes also advance revisions.
To remove public access, ask the agent to make the map private. This removes the public snapshot, disables live viewing, and queues deletion of the public page and preview. Previously downloaded copies remain outside KnowMapped’s control.
Technical reference
The server follows MCP Streamable HTTP and OAuth discovery conventions. Clients should begin with the MCP endpoint rather than configuring authorization endpoints manually.
https://mcp.knowmapped.com/mcphttps://mcp.knowmapped.com/.well-known/oauth-protected-resource/mcphttps://app.knowmapped.comhttps://mcp.knowmapped.com/mcp| Scope | Purpose |
|---|---|
maps:read | Search and retrieve maps available to the connected account. |
maps:create | Preflight, confirm, create, and recover map creation results. |
maps:write | Validate and apply edits to maps where the account has edit access. |
maps:publish | Make editable maps public or private, publish public snapshots, and check publication status. Does not grant content editing. |
Read resource://knowmapped/capabilities for limits, creation costs, and the current tool contract. Retrieval supports independent node_offset and edge_offset values, with page_size up to 200. Summary requests load counts without graph content; paginated requests load only the requested rows. Compare revisions between pages and restart if they change.
search_knowmapped_mapsSearch the authorized map library.
get_knowmapped_mapRetrieve full or compact pages, or graph-free summary counts.
get_knowmapped_map_adjacencyInspect a concept’s neighborhood by ID or exact unique label.
get_knowmapped_wheel_branchRetrieve a futures wheel branch and its causal metadata.
export_knowmapped_mapExport an authorized knowledge map or futures wheel as a portable .know file.
set_knowmapped_live_viewManage live-view access for a map.
get_knowmapped_layout_summaryInspect layout bounds and overlap statistics.
preflight_knowmapped_map_creationCheck eligibility, credits, and a retained graph draft.
create_knowmapped_mapValidate or prepare creation; credit use requires explicit confirmation.
confirm_knowmapped_map_creationConfirm a retained draft and settle its one-credit creation charge.
get_knowmapped_map_creation_resultRecover a creation result after a dropped response.
get_knowmapped_update_schemaGet the authoritative operation schema before constructing edits.
update_knowmapped_mapValidate or apply one atomic, revision-safe graph patch.
set_knowmapped_map_visibilityMake a map public or private; first publication creates a snapshot.
publish_knowmapped_mapPublish or republish completed edits to an already-public map.
get_knowmapped_publication_statusCheck snapshot revision, moderation, and delivery without downloading the graph.
Troubleshooting
Refresh the integration’s tools and begin a new conversation. An existing conversation may retain the tool list it received when it started.
Disconnect and reconnect KnowMapped in the client. Confirm that the client supports OAuth for remote MCP servers.
Confirm that the connection has maps:write and that your account can edit the map. Retrieve its current revision and check whether it is locked.
Request maps:publish and approve fresh consent. Refresh tool discovery. Your account still needs edit access; moderation or publishing restrictions may prevent publication.
Retry the identical request with its original key, then check publication status. Use a new key only for a new request.
Check whether access was revoked or the client lost a rotated refresh credential. Refresh credentials have no scheduled expiry in the standard deployment, but clients must renew and save them correctly.