Working with agents

How to connect AI agents, LLMs, and automation tools to your documentation.

AgentDocs offers four ways to connect agents and scripts:

MCP Server — the fastest integrationRecommended

Skip raw REST: the official MCP server gives your agent AgentDocs as native tools (keyword and semantic search, read, create, update, append, markdown-folder import, comments, image upload, sharing and more), addressable by slug or UUID. Connect to the hosted endpoint, with nothing to install, or run the npm package locally. The hosted endpoint also adds review tools for proposed changes, context collections and page-review metadata. Account tokens and space-scoped tokens both work.

Remote (hosted) — nothing to install

Point any remote-capable MCP client at our hosted endpoint and send your API token as an Authorization header. Both "Token <api_token>" and "Bearer <api_token>" are accepted here. Account tokens, space-scoped tokens and browser sessions all work — a space-scoped token stays confined to its own space, exactly as it does everywhere else. This is also the answer for catalog-based MCP gateways that cannot launch npx servers.

https://agentdocs.eu/mcp
Authorization: Token <your-token>

# Claude Code:
claude mcp add --transport http agentdocs https://agentdocs.eu/mcp \
  --header "Authorization: Token <your-token>"

Install in your client

Every entry below launches the same npx server — pick your client. You need an API token first: account-wide (Profile → Regenerate API Token) or space-scoped (Connect an agent at the top of a space; recommended for limiting an agent to a single space). The space-token form defaults to “Read only”: choose “Read and edit directly” if the agent should write pages. “Read and propose edits” needs the hosted endpoint above, which has the proposal tools.

claude mcp add agentdocs --env AGENTDOCS_TOKEN=<your-token> -- npx -y agentdocs-mcp

codex mcp add agentdocs --env AGENTDOCS_TOKEN=<your-token> -- npx -y agentdocs-mcp

# or in ~/.codex/config.toml:
[mcp_servers.agentdocs]
command = "npx"
args = ["-y", "agentdocs-mcp"]
[mcp_servers.agentdocs.env]
AGENTDOCS_TOKEN = "<your-token>"

// claude_desktop_config.json · .cursor/mcp.json ·
// ~/.codeium/windsurf/mcp_config.json · ~/.gemini/settings.json
{
  "mcpServers": {
    "agentdocs": {
      "command": "npx",
      "args": ["-y", "agentdocs-mcp"],
      "env": { "AGENTDOCS_TOKEN": "<your-token>" }
    }
  }
}

// .vscode/mcp.json — note the "servers" key
{
  "servers": {
    "agentdocs": {
      "command": "npx",
      "args": ["-y", "agentdocs-mcp"],
      "env": { "AGENTDOCS_TOKEN": "<your-token>" }
    }
  }
}

// settings.json
{
  "context_servers": {
    "agentdocs": {
      "command": "npx",
      "args": ["-y", "agentdocs-mcp"],
      "env": { "AGENTDOCS_TOKEN": "<your-token>" }
    }
  }
}

// opencode.json (project root) or ~/.config/opencode/opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agentdocs": {
      "type": "local",
      "command": ["npx", "-y", "agentdocs-mcp"],
      "environment": { "AGENTDOCS_TOKEN": "<your-token>" }
    }
  }
}

// .cursor/mcp.json (picked up by omp on start)
{
  "mcpServers": {
    "agentdocs": {
      "command": "npx",
      "args": ["-y", "agentdocs-mcp"],
      "env": { "AGENTDOCS_TOKEN": "<your-token>" }
    }
  }
}

{
  "mcpServers": {
    "agentdocs": {
      "command": "npx",
      "args": ["-y", "agentdocs-mcp"],
      "env": { "AGENTDOCS_TOKEN": "<your-token>" }
    }
  }
}

"command": "cmd",
"args": ["/c", "npx", "-y", "agentdocs-mcp"]

github.com/hoornet/agentdocs-mcp · npmjs.com/package/agentdocs-mcp

The raw endpoint

The raw endpoint is the simplest way to let an agent read a single page. It returns the page as Markdown with YAML frontmatter: no HTML, no JSON wrapper, no token. Anyone with the URL can read it, so use it only for pages that may be public.

Response format

The response is plain text (Content-Type: text/markdown; charset=utf-8) with the following structure:

---
title: Deployment Guide
shared_via: AgentDocs
last_updated: 2025-01-15T10:30:00.000Z
---

# Deployment Guide

This guide covers how to deploy the application to production.

## Prerequisites

- Docker 20.10+
- Kubernetes 1.25+
- Access to the container registry

## Steps

1. Build the container image:
   ```bash
   docker build -t myapp:latest .
   ```

2. Push to the registry:
   ```bash
   docker push registry.example.com/myapp:latest
   ```

3. Apply the Kubernetes manifests:
   ```bash
   kubectl apply -f k8s/
   ```

Frontmatter fields

Getting the raw URL

To get the raw URL for a page:

Example: fetching with curl

# Fetch the raw markdown for a shared page
curl https://agentdocs.eu/api/shared/abc123def456.../raw

# Response:
# ---
# title: Deployment Guide
# shared_via: AgentDocs
# last_updated: 2025-01-15T10:30:00.000Z
# ---
#
# # Deployment Guide
# ...

# You can also pipe it directly to other tools:
curl -s https://agentdocs.eu/api/shared/abc123.../raw | head -20

Practical examples

Feeding docs to an assistant

If your assistant can fetch URLs (for example, with a web-fetch tool), put the raw URL in its instructions. Each fetch returns the current version of the page:

# In a system prompt or instruction set:

You have access to our deployment documentation.
Fetch the latest version from:
https://agentdocs.eu/api/shared/abc123def456/raw

Use this documentation to answer questions about
deployment procedures, troubleshooting, and configuration.

Wrapping the URL in a tool

Many agent frameworks let you declare a tool that calls a URL. The format depends on the framework; this generic sketch shows the idea. For full read and write access, use the MCP server instead.

{
  "name": "get_deployment_docs",
  "description": "Fetch the latest deployment documentation from AgentDocs",
  "parameters": {},
  "implementation": {
    "type": "http",
    "method": "GET",
    "url": "https://agentdocs.eu/api/shared/abc123def456/raw"
  }
}

CI/CD pipelines

Pull documentation into build pipelines, test suites or deployment scripts. Requests without a token are limited to 300 per 15 minutes per IP address:

# GitHub Actions example
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Fetch deployment runbook
        run: |
          mkdir -p docs
          # -f fails the step if the link was revoked or has expired (404)
          curl -fsS https://agentdocs.eu/api/shared/abc123.../raw \
            > docs/runbook.md

      - name: Validate against runbook
        run: python scripts/validate_deployment.py docs/runbook.md

Python example

import requests

def fetch_agentdocs_page(share_token: str) -> dict:
    """Fetch a shared AgentDocs page and split off its frontmatter."""
    url = f"https://agentdocs.eu/api/shared/{share_token}/raw"
    response = requests.get(url, timeout=10)
    response.raise_for_status()  # 404 if the link was revoked or has expired

    text = response.text
    metadata = {}
    if text.startswith("---\n"):
        # The title is not quoted, so a YAML parser can fail on titles
        # such as "Deploy: production". Split each "key: value" line instead.
        header, _, content = text[4:].partition("\n---\n")
        for line in header.splitlines():
            key, _, value = line.partition(": ")
            metadata[key] = value
        return {"metadata": metadata, "content": content.lstrip("\n")}

    return {"metadata": metadata, "content": text}

# Usage:
page = fetch_agentdocs_page("abc123def456")
print(f"Title: {page['metadata']['title']}")
print(f"Updated: {page['metadata']['last_updated']}")
print(f"Content length: {len(page['content'])} chars")

Private access with tokens

To read pages without making them public, or to create, update or delete pages, your agent needs a token. An account API token can do everything you can. A space token is limited to one space and to the permission you chose when you created it.

# List workspaces (account API token only; a space token gets 403)
curl https://agentdocs.eu/api/workspaces \
  -H "Authorization: Token your_api_token_here"

# Create a page programmatically
curl -X POST https://agentdocs.eu/api/spaces/SPACE_ID/pages \
  -H "Authorization: Token your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Auto-generated Changelog",
    "slug": "changelog-2025-01-15",
    "content": "# Changelog\n\n## v2.1.0\n- Added new feature X\n- Fixed bug Y"
  }'

# Update an existing page. Send the version you last read: if someone
# saved since, you get 409 Conflict instead of overwriting their change.
curl -X PUT https://agentdocs.eu/api/pages/PAGE_ID \
  -H "Authorization: Token your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{"content": "# Updated content...", "version": 7}'

Learn how to get your API token in the API authentication guide.

Webhook notifications

Instead of polling, set up a webhook: AgentDocs sends an HTTP POST to your URL when a page is created, updated, renamed, moved or deleted.

# When a page is updated, your webhook receives:
{
  "event": "page.updated",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "page_id": "...",
    "space_id": "...",
    "workspace_id": "...",
    "title": "Deployment Guide",
    "slug": "deployment-guide",
    "author_name": "Alice",
    "version": 7,
    "previous_version": 6,
    "content": "# Deployment Guide\n...",
    "diff": { "type": "lines", "additions": 1, "deletions": 0, "preview": "+Updated deployment steps" }
  }
}

The page.created and page.updated payloads include the full page content, so your agent usually needs no second request. Read more in the Webhooks guide.

Summary

Skill files

AgentDocs publishes three plain-text files that describe its API for agents. Point an agent at one of them to learn the API; it still needs a token for anything beyond public share links.

curl https://agentdocs.eu/llms.txt

curl https://agentdocs.eu/llms-full.txt