Agents & MCP

tela has a built-in MCP server, so your AI assistant becomes a first-class part of your wiki — it searches, reads, and (with permission) writes pages and builds decks. Connect once, then just ask in plain language.

Connect your assistant

[!TIP] Your own agent is unlimited. Driving tela through your connected agent runs on your model and your tokens — so it doesn't count against your monthly built-in-AI answers, on any plan including Free. Only the in-app ask your docs meters against your plan. See [[Plans & billing]].

Each guide is a step-by-step walkthrough with screenshots:

• 💬 [[Connecting ChatGPT]] — one-click install from ChatGPT's plugin directory
• ✦ [[Connecting Claude]] — claude.ai and the desktop app

ChatGPT installs from the directory with nothing to configure. Everywhere else, point the client at your tela endpoint and sign in once through tela (OAuth — nothing to copy):

https://telawiki.com/api/mcp

[!TIP] That's all most people need. Open a section below only if you use a different tool or want token-based access.

Claude Code (terminal) — install the tela plugin, which brings the connection with it:

/plugin marketplace add zcag/tela-claude-plugin
/plugin install tela@telawiki

Then run /mcp and pick Authenticate. The plugin also teaches Claude Code when to reach for your wiki, so you can ask a question in plain language instead of naming a tool.

Already signed into Claude Code with your Claude account? Connectors you added on claude.ai are already there (run claude mcp list and you'll see claude.ai Tela) — you don't need the plugin. You can also add the endpoint by hand, which is the route for API-key mode or a different / self-hosted instance:

claude mcp add --transport http tela https://telawiki.com/api/mcp

Cursor / VS Code — ~/.cursor/mcp.json:

{ "mcpServers": { "tela": { "url": "https://telawiki.com/api/mcp" } } }

Any stdio-only host — run the tela-mcp proxy with a token:

{
  "mcpServers": {
    "tela": {
      "command": "npx",
      "args": ["-y", "tela-mcp@latest"],
      "env": { "TELA_BASE_URL": "https://telawiki.com", "TELA_API_KEY": "tela_pat_..." }
    }
  }
}

Prefer HTTP where you can — the proxy is only a thin stdio↔HTTP bridge for hosts that can't speak HTTP.

• OAuth (default). The web apps, Claude Code, and Cursor send you to tela to sign in — nothing to paste. Needs a publicly reachable tela.
• Personal access token (PAT). Works everywhere, including self-hosted and the stdio proxy. Create one in Settings → API Keys and pass it as Authorization: Bearer tela_pat_…. Scopes (read / write / admin), space-pinning, and expiry in [[API & personal access tokens]].

What your assistant can do

Once connected, just ask — it picks the right tool:

• Find & answer — keyword search and semantic research across your pages and attached files (PDFs, docs).
• Write & edit docs — create pages, rewrite a single section, add callouts, tables, diagrams, kanban — all real markdown, and check its own work: it can lint a page for markdown that renders differently than it reads, and preview the rendered result. See [[The editor & blocks]].
• Build & present decks — ask for slides and it authors a styled deck you can Present or export to PDF/PPTX. See [[Presentations & decks]].
• Build & edit spreadsheets — ask for a sheet (a budget, tracker, or table with totals) and it writes the grid with real formulas and formatting, then edits it precisely — set a cell, insert a row, reformat a range — with formulas re-referencing automatically. See [[Spreadsheets]].
• Import your files — point it at a folder of Word docs, spreadsheets, and PDFs and it brings them in as a page tree, turning spreadsheets into live sheets and attaching everything else. See [[Importing your files]].
• Work through comments — read the comments people left on a page, or pull an inbox of every open thread in a space, then reply inside the thread and mark it resolved once it's handled. It can poll for just what's new since it last looked, so a teammate's comment becomes an agent's to-do without anyone re-typing it.
• Share & tidy — mint public links, invite a colleague to a space by email (even if they have no tela account — they get an invitation), find near-duplicates, suggest cross-links. See [[Sharing a space]].
• Generate docs from code — trigger an [[Atlas — automated documentation|Atlas]] run to document a git repo or Jira project.

Everything runs with your permissions, and writing needs editor access on the target space.

• Read/search: list_spaces, get_space, list_pages, get_page, search (keyword/full-text — always available), research (semantic — assembled, cited grounding for a question), list_backlinks, read_chunk, fetch. research/read_chunk span pages and uploaded files.
• Knowledge & hygiene: related_pages, suggest_links, find_overlaps, knowledge_gaps (admin).
• Write (write scope): create_page, update_page, patch_page (one section), move_page, delete_page, create_space, update_space, delete_space.
• Sharing (write scope): share_page / list_shares / revoke_share mint and manage public links. invite_to_space gives a person access to a space by email — space owner only; an existing account is added straight away, an unknown address is emailed an invitation and joins when they sign up. See [[Sharing a space]]. To publish a whole space, flip its visibility instead — see [[Publishing & public URLs]].
• Comments: list_comments reads them — pass a page for its full threads (each comment with its replies, author, timestamp, the passage it's anchored to, and whether it's resolved), or a space for an inbox of open threads across every page. It returns a cursor; hand that back as since next time and you get only threads with new or edited activity — including ones somebody just replied to. add_comment writes one: on its own it starts a thread anchored to a passage, with parent_id it replies inside an existing one. update_comment resolves a thread (or reopens it), and can edit the text of a comment the agent wrote itself — never someone else's. Reading needs read scope; writing needs write scope, and both need editor access on the space. Agents can't delete comments — removing what a person wrote stays a human action.
• Pages — checking the render: lint_page reports where the reader will show something other than what the markdown says (an unrecognized block that unwraps, raw HTML that's dropped, a collapsible missing its blank lines, a wikilink pointing at nothing), and preview_page renders a page and reads it back so an agent can see its own output instead of authoring blind. Advisory — neither blocks a write, and a write that trips the lint returns the findings alongside its result. Same check people get in the editor, see [[The editor & blocks]].
• Decks: deck_authoring_guide, lint_deck, preview_deck — the agent reads the guide, then lints and previews before handing back. generate_deck_image / treat_deck_image — raster-image generation for slide assets (advanced; most decks don't need these directly).
• Sheets: sheet_authoring_guide (the sheet text format, formulas, and styling) and edit_sheet — a structured editor that sets cells, inserts/deletes rows & columns, styles ranges, freezes, and manages tabs, with formulas re-referencing automatically. Agents make a sheet with create_page (the sheet property) and change it with edit_sheet rather than rewriting the markdown by hand.
• Files (write scope): list_attachments, list_space_files (every file in a space, including the ones sitting at the space root rather than on a page — nothing else can find those), upload_attachment, request_attachment_upload / confirm_attachment_upload, delete_attachment — images render inline, PDFs preview in-page and are indexed for research. Each file comes back with two links: a download_url for the agent to fetch the bytes, and a share_url — the one to ask for when you want the file sent to you, since it opens a preview page and unfurls as a card in chat instead of downloading.
• Import: import_guide — the recipe for bringing an existing folder of files in as a page tree: it converts Office files locally (Word → pages, spreadsheets → live sheets), attaches PDFs/images, and bulk-creates the tree via the import endpoint's dry-run → confirm flow. See [[Importing your files]].
• Atlas (write scope): atlas_list_projects lists the Atlas projects you can see; atlas_run triggers a full documentation run for a project (management access required); atlas_run_status reads a run's status, current stage, coverage metrics, and statistics. See [[Atlas — automated documentation]].
• Feedback: submit_feedback.

[!TIP] Bulk-authoring or a flaky link? Pass an idempotency_key to create_page, create_space, or add_comment — a retry with the same key returns the original result instead of duplicating.

• It claims it did something but nothing changed (ChatGPT) → the connector wasn't engaged in that chat. Engage it from the composer "+" menu (or start a new chat), then verify — see [[Connecting ChatGPT]].
• 401 / tools don't appear → credential missing or revoked. For OAuth, re-run Connect/Authenticate; for a PAT, the header must be exactly Authorization: Bearer <token>.
• Write fails with a scope error → your token is read-scoped, or your account lacks editor access on that space.
• invite_to_space says owner role required → only a space owner can invite; ask an owner, or have them make you one.
• research 503s → the instance's embedder isn't configured; search (full-text) always works.
• atlas_run returns ai_unavailable → the instance needs both an embedder (TELA_RAG_EMBED_URL) and a chat model (TELA_LLM_URL) configured. See [[Self-Hosting]].
• Can't connect from the web apps → OAuth needs a public tela; otherwise use Claude Code or the stdio proxy with a PAT.
• stdio proxy keeps dropping (-32000) → update to tela-mcp@latest, or connect over HTTP directly.

See also [[Troubleshooting & FAQ]].