Skip to content

External AI Agents (MCP)

EchoLore includes a built-in MCP (Model Context Protocol) server, letting external AI agents such as ChatGPT and Claude connect to your Wiki knowledge.

Tool Scope Function
wiki_search read Vector search over the Wiki
wiki_read_page read Fetch a page’s content as markdown (paged for long pages)
wiki_list_spaces read List visible spaces and writability
wiki_list_pages read List visible pages (by space, newest first, with hierarchy) for inventory and browsing
wiki_maintenance_report read Knowledge audit (overdue reviews, stale/empty pages, etc.)
wiki_create_page write Create a new page from markdown
marketing_query_metrics reporting Marketing metrics aggregation (cost, conversions, sessions + derived CPA/ROAS etc.)
marketing_list_dashboards reporting List reporting dashboards
marketing_get_dashboard reporting Read a dashboard definition (widgets, metrics, filters)
marketing_data_status reporting Data freshness, sync health, and pending approvals

Read tools are filtered by the token creator’s read permissions — information from inaccessible pages is never returned. Marketing tools additionally require the token creator to hold the marketing.view permission. Tool calls are rate limited per token (60 calls per 5 minutes).

With a reporting-scoped token, you can simply ask ChatGPT or Claude things like “summarize last week’s ad spend and CPA” or “build this month’s dashboard report” — the agent reads the dashboard definition, queries the metrics, and assembles the report. Aggregation semantics (missing days are never treated as zero, media conversions are never summed across sources, currencies stay separate) are identical to the web UI because both use the same query API.

OAuth-capable clients (ChatGPT / Claude connectors)

Section titled “OAuth-capable clients (ChatGPT / Claude connectors)”

EchoLore embeds an OAuth 2.1 authorization server. Point your client at https://<your-domain> as the authorization server and it will be discovered automatically. On first connect, an admin consent screen is shown; once allowed, tokens are issued and refreshed automatically (30-day access tokens with rotating refresh tokens).

  1. Open Admin console → AI Settings → External AI Agent Access (MCP)
  2. Choose a token name, scopes (read / write / reporting), and an expiry (never / 7 / 30 / 90 days), then issue
    • Defaults to read (least privilege). Add write only for page creation, reporting for marketing reports
  3. The plaintext token (ech_agt_...) is shown exactly once — copy and store it safely

Tokens act with the issuing admin’s permissions and can be revoked instantly at any time. Recent per-token usage (success/failure, tool, timestamp) is visible in the admin console.

Configure your MCP client as follows:

{
"mcpServers": {
"echolore": {
"type": "http",
"url": "https://<your-domain>/mcp",
"headers": {
"Authorization": "Bearer ech_agt_..."
}
}
}
}
  • Implements protocol revision 2026-07-28 (stateless MCP) only
    • Legacy initialize-handshake clients are not supported
  • Stateless Streamable HTTP, POST only
  • server/discover advertises supported versions and capabilities
  • Structured output (outputSchema / structuredContent) and tool annotations are supported
  • Bearer token authentication (OAuth-issued tokens use the same format)

The repository ships skills/echolore-wiki-maintenance/SKILL.md — a skill definition to load into agents covering audit, research, and article-creation workflows, including the rule that page creation tools may only be used on explicit request.

  • Tokens are stored as SHA-256 hashes only (plaintext is never shown again)
  • Optional token expiry (OAuth-issued tokens always expire after 30 days)
  • Tokens are automatically invalidated if the issuing account is deleted or suspended
  • Page creation is always attributed to the issuing user and recorded in the audit log
  • OAuth consent requires an admin session; authorization codes are single-use with mandatory PKCE, and refresh tokens rotate on every use
  • No tool modifies existing pages (destructive operations are excluded by design)