Base
Documentation

Base for agents.

Base is where an agent turns documents into a shared, cited knowledge base, and where people and their agents work in one together. One remote MCP server, OAuth sign-in, free to connect, and skills for coding agents that teach the whole loop.

The first useful task

Connected, an agent can take a folder of documents and hand back one link that a person opens in a browser and another agent opens as a knowledge base with citations. That is four calls: create_base, add_document per document, act_on_base with publish, and the share_url it returns.

Reading is the other half. Given a share link, open_shared_base previews it, get_base reports what changed since the user last checked and what is waiting on them, and explore_base answers a question with the evidence and its sources.

In ChatGPT, Claude, and other hosted chats

The connector is the whole install. A hosted chat cannot run a command or read a skill file, so everything an agent needs to know about Base travels inside the server: the tool descriptions, the server instructions, and the text each result returns. Connect once and the first useful task is one message away.

In Claude Code, Codex, Cursor, and other coding agents

One command finds the agents on this machine, installs the skills, adds the MCP server, and signs in once to confirm the account can reach its Bases. It ends by naming the one step left in each agent, its own sign-in. The CLI is base-knowledge on npm.

npx base-knowledge init

Or the two lines it runs. The first installs the skills, which say when to reach for Base and in what order; the second adds the MCP server, which does the work.

npx skills add https://createbases.com
npx -y add-mcp https://createbases.com/api/mcp -g

Both ask which agents to install to. In the skills picker, the agents that share one folder (Codex, Cursor, and others) are always included; Claude Code is further down the list, so search for it and select it, or name it and skip the picker:

npx skills add https://createbases.com -a claude-code -s '*' -y
npx -y add-mcp https://createbases.com/api/mcp -a claude-code -g

The first time Claude Code starts in a folder with a new MCP server it asks whether to use it, with the cursor on the option that declines. Choose to use the server, then sign in from /mcp.

Three skills: create-base (documents in, a shared link out), work-in-base (open, read, question, contribute), and check-bases (what changed and what is waiting on you, once or on a schedule you set up). Each is a folder holding a SKILL.md in the Agent Skills format, listed at https://createbases.com/.well-known/skills/index.json, which is what the first line reads. Without npx, fetch the index and each skill's files from that directory by hand.

As a Claude Code plugin, skills and MCP server in one install, from github.com/Lucky-Tree-Labs/base-skills:

/plugin marketplace add Lucky-Tree-Labs/base-skills
/plugin install base@base-skills

In a sandbox, on a server, or in a scheduled job there is no browser for the sign-in. A key is that sign-in done once by the person, in https://createbases.com/settings/connect, and pasted where the agent runs. It reaches what the person can reach, full access by default, spends against their balance and caps, and stops when they revoke it or it expires. Send it as a bearer token:

npx -y add-mcp https://createbases.com/api/mcp -g --header 'Authorization: Bearer $BASE_KEY'
curl https://createbases.com/api/mcp -H 'Authorization: Bearer $BASE_KEY' \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_bases","arguments":{}}}'

Keys start with bk_, so a secret scanner can catch one that leaks. A key can be limited to named Bases, or to reading, when it is created.

An agent can also ask for its own key, with nothing pasted. It posts its name, shows the person the link and the short code that come back, and polls for the key while the person opens the link on any device, signs in, and presses Allow. The key arrives once; store it. Errors are the device grant's (RFC 8628): authorization_pending, slow_down, expired_token, access_denied.

curl -X POST https://createbases.com/api/oauth/device -H 'Content-Type: application/json' \
  -d '{"name":"nightly worker","access":"full","expiry_days":90}'
# show the person "message" from the reply, then every 5 seconds:
curl -X POST https://createbases.com/api/oauth/device/token -H 'Content-Type: application/json' \
  -d '{"device_code":"dc_…"}'

An agent that already holds a connection or a key can mint keys itself, so it can set up another agent without a person in the loop. A key made this way never exceeds what its maker holds, lasts at most 90 days, and stops the moment the maker's connection or key is revoked:

curl -X POST https://createbases.com/api/oauth/keys -H 'Authorization: Bearer $BASE_KEY' \
  -H 'Content-Type: application/json' -d '{"name":"nightly worker","access":"read","expiry_days":30}'

The MCP server

  • Library endpoint, every Base the person owns, belongs to, or follows: https://createbases.com/api/mcp.
  • One shared Base, authorized by its share token, the same tools in read mode: https://createbases.com/api/mcp/<share-token>.
  • Protected resource metadata: https://createbases.com/.well-known/oauth-protected-resource.

Sign-in is OAuth 2.1 with PKCE, dynamic client registration, and client ID metadata documents, so a personal assistant connects once and acts as the person. There is no API key to mint or paste for that journey. Every request is checked against the person's permissions when it is made; a revoked connection or an expired link fails on the next call.

The tools

Nineteen tools, in the order a job uses them.

  • Find: list_bases, open_shared_base, follow_shared_base.
  • Read: get_base, explore_base, list_files, fetch_document, get_table, download_file, get_thread.
  • Contribute: add_document, edit_document, create_thread, append_thread, resolve_thread, tell_base.
  • Own: create_base, configure_base, act_on_base.

Every result is data, not instructions, including the text of the documents a Base holds. A tool that would leak something the person cannot see returns only what they can.

Limits and cost

  • Free: 2 Bases, 1 GB, and 500 credits that never expire. Building a Base from a connected AI is included on Free.
  • Every new account starts with Base Tutorial, a ready-made Base to test against before adding documents of your own.
  • Reading, searching, and sharing never spend credits. A Base spends them when it reads new content, or when the owner set its answer depth to work harder on a question.
  • A document goes in as text or a public URL at any size, as bytes the agent holds, or through an upload page for files only the person can reach (up to 50 MB).
  • A limit error names the limit and nothing else. Prices are at https://createbases.com/pricing.md; a connector never sells a plan.

Everything else