AvailableProfessional

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

Tools for searching, creating, editing, and publishing maps.

Clients can retrieve map data, prepare drafts, apply validated edits to concepts, relationships, and wheel branches, and publish public snapshots.

01

Find and retrieve

Search maps available to the account, then retrieve graph data, paginated results, or count-only summaries.

02

Create and extend

New map creation costs one generation credit and requires confirmation. Extend existing maps without a creation charge.

03

Publish and update

Set map visibility, publish edits as public snapshots, and check moderation and delivery status.

04

Edit and arrange

Apply validated changes to concepts, relationships, wheel branches, map details, and layouts.

Connection guide

Register the endpoint, complete OAuth, load the tools.

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.

  1. 01

    Configure the resource server

    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.

  2. 02

    Resolve OAuth metadata

    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.

  3. 03

    Register a public client

    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.

  4. 04

    Authorize with PKCE

    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.

  5. 05

    Initialize and load tools

    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

Use KnowMapped with ChatGPT or Codex.

ChatGPT

Add a custom app.

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 requirements

Codex

Add a remote MCP server.

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 list
Read OpenAI’s Codex MCP guide

Access and billing

Your account permissions still apply.

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

Publishing updates the public snapshot.

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

Discovery, authorization, and tools.

The server follows MCP Streamable HTTP and OAuth discovery conventions. Clients should begin with the MCP endpoint rather than configuring authorization endpoints manually.

Discovery

MCP endpoint
https://mcp.knowmapped.com/mcp
Protected resource
https://mcp.knowmapped.com/.well-known/oauth-protected-resource/mcp
Authorization server
https://app.knowmapped.com

OAuth

Grant
Authorization code with PKCE S256
Client registration
Client ID Metadata Documents, with Dynamic Client Registration fallback
Resource
https://mcp.knowmapped.com/mcp
OAuth scopes used by KnowMapped MCP tools
ScopePurpose
maps:readSearch and retrieve maps available to the connected account.
maps:createPreflight, confirm, create, and recover map creation results.
maps:writeValidate and apply edits to maps where the account has edit access.
maps:publishMake 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.

Current tools

search_knowmapped_maps

Search the authorized map library.

get_knowmapped_map

Retrieve full or compact pages, or graph-free summary counts.

get_knowmapped_map_adjacency

Inspect a concept’s neighborhood by ID or exact unique label.

get_knowmapped_wheel_branch

Retrieve a futures wheel branch and its causal metadata.

export_knowmapped_map

Export an authorized knowledge map or futures wheel as a portable .know file.

set_knowmapped_live_view

Manage live-view access for a map.

get_knowmapped_layout_summary

Inspect layout bounds and overlap statistics.

preflight_knowmapped_map_creation

Check eligibility, credits, and a retained graph draft.

create_knowmapped_map

Validate or prepare creation; credit use requires explicit confirmation.

confirm_knowmapped_map_creation

Confirm a retained draft and settle its one-credit creation charge.

get_knowmapped_map_creation_result

Recover a creation result after a dropped response.

get_knowmapped_update_schema

Get the authoritative operation schema before constructing edits.

update_knowmapped_map

Validate or apply one atomic, revision-safe graph patch.

set_knowmapped_map_visibility

Make a map public or private; first publication creates a snapshot.

publish_knowmapped_map

Publish or republish completed edits to an already-public map.

get_knowmapped_publication_status

Check snapshot revision, moderation, and delivery without downloading the graph.

Troubleshooting

Start with the client’s tool refresh.

Tools do not appear

Refresh the integration’s tools and begin a new conversation. An existing conversation may retain the tool list it received when it started.

Sign-in does not open

Disconnect and reconnect KnowMapped in the client. Confirm that the client supports OAuth for remote MCP servers.

A map cannot be changed

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.

Publishing is unavailable

Request maps:publish and approve fresh consent. Refresh tool discovery. Your account still needs edit access; moderation or publishing restrictions may prevent publication.

A publication response was lost

Retry the identical request with its original key, then check publication status. Use a new key only for a new request.

A connection needs sign-in again

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.