The tela MCP server

tela ships a built-in Model Context Protocol server, so AI agents are first-class users of your wiki — they read, search, and write the same markdown your team does. This page is the public reference for connecting to it.

Endpoint

URL

https://tela.cagdas.io/api/mcp

Transport

Streamable HTTP (the current MCP transport; SSE is not used).

Auth

OAuth 2.1 with PKCE (via WorkOS AuthKit), or a Personal Access Token as a bearer header.

Connecting

Claude

In Claude, add tela as a custom connector and point it at the endpoint URL above. Claude runs the OAuth flow — you sign in to tela and consent, and the tools become available in chat. No manual token handling.

ChatGPT

In ChatGPT's connector / Developer Mode settings, add a connector with the endpoint URL above and complete the OAuth sign-in. tela also exposes the search + fetch pair used by Deep Research.

Any MCP client (npm proxy)

For stdio-based hosts, the published tela-mcp package is a thin proxy that forwards stdio to the HTTP endpoint with your token:

{
  "mcpServers": {
    "tela": {
      "command": "npx",
      "args": ["-y", "tela-mcp"],
      "env": {
        "TELA_URL": "https://tela.cagdas.io",
        "TELA_TOKEN": "<your personal access token>"
      }
    }
  }
}

Modern hosts that speak Streamable HTTP can skip the proxy and connect to /api/mcp directly.

Tools

Twenty tools, with read and write cleanly separated. Every tool carries a human-readable title and read/write annotations; writes are scoped by your token's permissions.

Read

• list_spacesList the spaces you can access.
• get_spaceRead a space and its metadata.
• list_pagesList pages in a space, as a tree.
• get_pageRead a page (canonical markdown).
• list_backlinksPages that link to a given page.
• read_chunkRead a slice of a large page.
• searchFull-text search across pages.
• search_bodiesSearch returning matching page bodies.
• semantic_searchVector search over page content.
• fetchFetch a document by id (Deep Research).

Write

• create_spaceCreate a new space.
• update_spaceRename or edit a space.
• delete_spaceDelete a space.
• create_pageCreate a page from markdown.
• update_pageEdit a page body or title.
• move_pageRe-parent or reorder a page.
• delete_pageDelete a page.
• add_commentComment on a page.
• import_miraImport an external URL as a page.
• submit_feedbackSend feedback to the maintainers.

Resources

tela exposes pages and spaces as MCP resource templates, so agents can reference them by URI:

• tela://page/{id} — a page by id.
• tela://space/{id} — a space by id.

Interactive widgets

On hosts that support MCP Apps / interactive UI, tela returns two embedded widgets — a page reader and search-results cards — so results render as interactive components instead of raw text.

Permissions & safety

• Agent tool calls run with your account's permissions — an agent can only touch what you can.
• Write tools are gated separately from read tools; read-only connections never mutate content.
• Page bodies are canonical markdown — what an agent writes is exactly what your team sees.
• See the privacy policy for what is collected and shared.

Limitations

• Semantic search needs an embedder. semantic_search and read_chunk return 503 if the instance has no embedding model configured. Full-text search and search_bodies always work.
• Large pages are capped. get_page and fetch truncate bodies beyond ~80k characters and set truncated: true; read specific sections with semantic_search + read_chunk.
• Writes need editor permission. Create/update/delete tools require editor access on the target space; a read-scoped token or a viewer account can't write.
• import_mira is allowlisted. It fetches only operator-configured hosts over HTTPS, server-side, following no redirects.

Troubleshooting

Connect fails / "couldn't register"

The host couldn't complete OAuth. Re-add the connector with the exact URL https://tela.cagdas.io/api/mcp, then sign in and consent when the tela login screen appears.

401 / tools don't appear

The token is missing or invalid. For the OAuth flow, reconnect; for the npm proxy, check TELA_TOKEN is a current Personal Access Token.

Tool returns 503 rag_disabled

Semantic search isn't configured on this instance — use search / search_bodies instead.

A page comes back truncated

Expected for very large pages (truncated: true). Use semantic_search to find the relevant section, then read_chunk.

Write tool returns a permission error

Your account or token lacks editor access to that space.

Still stuck? Email [email protected] — the source is on GitHub.

Source, support & security

tela is open-source at github.com/zcag/tela; the MCP proxy is tela-mcp on npm. Questions and support: [email protected]. Report security vulnerabilities privately to [email protected] — please don't open a public issue for security reports.