agentailor-mcp

An MCP server that connects your AI assistant to Agentailor — search the blog, read articles in full, and pull docs from the open-source repos, all over the Model Context Protocol.

Use it with no clone required:

• npx (local stdio) — run npx @agentailor/mcp as a command in Claude Desktop and other local clients.
• Hosted HTTP (coming soon) — a zero-install Agentailor-hosted endpoint you point your client at.

Scaffolded with @agentailor/create-mcp-server on FastMCP — the tool building its own ecosystem.

Tools

Tool	What it does
agentailor_get_blog_index	Returns the blog's content map (Markdown) — every published article with title, date, tags, summary.
agentailor_search_articles	Ranked article search in one tool: free-text query, tags filter, guidesOnly, limit, response_format. Returns JSON.
agentailor_read_article	Fetches a single article's full Markdown by its blog.agentailor.com .md URL.
agentailor_list_repos	Lists the public repos in the agentailor GitHub org. Returns JSON.
agentailor_read_repo_doc	Reads a README.md or docs/*.md from a given org repo (Markdown).

Scope is Agentailor's public content: the blog and the open-source org repos. The list/search tools (search_articles, list_repos) return structured JSON; the content tools return raw Markdown.

Use it

Connect your client (local stdio via npx)

The server runs as a local stdio command — npx -y @agentailor/mcp — so any MCP client can launch it. Add the config for your client below. No install step; npx fetches the package on first run.

Claude Desktop

In claude_desktop_config.json (Settings › Developer › Edit Config), then restart Claude Desktop:

{
  "mcpServers": {
    "agentailor": {
      "command": "npx",
      "args": ["-y", "@agentailor/mcp"]
    }
  }
}

Cursor

Same schema as Claude. Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects):

{
  "mcpServers": {
    "agentailor": {
      "command": "npx",
      "args": ["-y", "@agentailor/mcp"]
    }
  }
}

VS Code / GitHub Copilot

Create .vscode/mcp.json in your workspace. Note the top-level key is servers (not mcpServers):

{
  "servers": {
    "agentailor": {
      "command": "npx",
      "args": ["-y", "@agentailor/mcp"]
    }
  }
}

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.agentailor]
command = "npx"
args = ["-y", "@agentailor/mcp"]

Or use the CLI: codex mcp add agentailor -- npx -y @agentailor/mcp.

Any other MCP client

Run it as a stdio server with this command:

npx -y @agentailor/mcp

Raising the GitHub rate limit (optional)

The repo tools read public GitHub data, so no token is required. If you hit GitHub's unauthenticated rate limit (60 requests/hour), set a GITHUB_TOKEN (any token with public read access) to raise it to 5,000/hour. In a JSON config, add an env block to the server entry:

{
  "mcpServers": {
    "agentailor": {
      "command": "npx",
      "args": ["-y", "@agentailor/mcp"],
      "env": { "GITHUB_TOKEN": "ghp_your_token" }
    }
  }
}

For Codex, add it under the server's env in config.toml; for VS Code, add it under the servers entry.

Hosted HTTP (coming soon)

A zero-install, Agentailor-hosted HTTP endpoint is planned — point any streamable-HTTP MCP client at a single URL, nothing to install or run. It isn't live yet; for now use the npx setup above. The endpoint URL will be published on agentailor.com when it's ready.

Designed to the "Writing Effective Tools for AI Agents" playbook

These tools follow the five principles from Agentailor's Writing Effective Tools for AI Agents — here's exactly how:

Principle	How this server applies it
1. Strategic selection	One agentailor_search_articles covers discovery by topic, by tag, and guides-only — instead of four fragmented search tools. Tools map to how you actually work, not to endpoints.
2. Clear namespacing	Every tool is prefixed agentailor_, so it never collides with other MCP servers on your client.
3. Meaningful context	Read tools take response_format: "concise" | "detailed". Results carry titles, tags, and summaries you can reason on — not bare IDs.
4. Token efficiency + guiding errors	Search defaults to 20 results with an overflow hint that tells the agent how to narrow. A GitHub rate-limit returns "set a GITHUB_TOKEN" guidance, not a raw 403.
5. Descriptions as prompts	Each tool description includes a When to use section with example calls, and every parameter documents its shape with an example.

Deploy your own HTTP instance

The HTTP transport serves the MCP endpoint at POST /mcp and a GET /health check.

Native Node host

On any platform that runs a Node web service from this repo:

• Build command: pnpm install --frozen-lockfile && pnpm build
• Start command: pnpm start:http
• Health check path: /health
• Environment:
  • GITHUB_TOKEN — a token with public read access (recommended on a shared/hosted instance; raises the GitHub limit to 5,000/hour).
  • PORT — most hosts inject this automatically; the server reads it. Defaults to 3000 if unset.

Node 20 is pinned via engines and .node-version.

Docker

A Dockerfile is included for running the server on any container host. The TRANSPORT build arg selects the entrypoint:

docker build --build-arg TRANSPORT=http -t agentailor-mcp-http .
docker run -p 3000:3000 -e GITHUB_TOKEN=ghp_your_token agentailor-mcp-http

Connect any HTTP MCP client to http://<host>:3000/mcp.

Configuration

Variable	Required	Purpose
PORT	No	HTTP transport port (default 3000). Injected by most hosts. Ignored by stdio.
GITHUB_TOKEN	No	Raises the GitHub API limit for the repo tools from 60/hr to 5,000/hr. Any token with public read access works. Recommended on a hosted/shared instance.
BLOG_BASE_URL	No	Override the blog origin (for local/staging testing).

No credentials are required to run — all exposed data is public.

Develop locally (contributors)

Clone and run from source:

pnpm install
pnpm build

# stdio (local clients)
pnpm start:stdio

# HTTP on PORT (default 3000)
pnpm start:http

Dev mode with reload: pnpm dev:stdio or pnpm dev:http.

pnpm test          # Vitest unit tests
pnpm typecheck     # tsc --noEmit
pnpm format:check  # Prettier check
pnpm inspect       # MCP Inspector against the HTTP server
pnpm inspect:stdio # list tools over stdio

Releasing

The npm package publishes via GitHub Actions when a GitHub Release is published:

1. Bump version in package.json (and src/server.ts), commit.
2. Cut a GitHub Release / tag.
3. The publish workflow runs the test/build gates and publishes @agentailor/mcp to npm (auth via the NPM_TOKEN repo secret).

Learn more

• Writing Effective Tools for AI Agents — the design playbook this server follows
• @agentailor/create-mcp-server — the scaffolder
• FastMCP · Model Context Protocol

License

Apache 2.0 © Agentailor