Can Agents Use

Find tools an AI agent can actually use.

Can Agents Use is a public, file-backed directory of APIs, CLIs, MCP servers, browser-operable products, pricing pages, docs, sandboxes, and account setup flows. The website is the live searchable surface. This README is the GitHub surface: a compact map of the project, the data, and the agent-facing interfaces.

What Is In The Catalog

The catalog is generated from data/tools and data/taxonomy.json, then exposed through the website, API, MCP endpoint, CLI, and LLM-friendly Markdown exports.

For current catalog contents, use the live search at canagentsuse.com or fetch /api/agent/catalog.

Every tool record is scored from evidence, not vibes. A good record answers:

• Can an agent operate it through an API, CLI, MCP server, or browser?
• Are docs, pricing, auth, and account setup clear enough to automate safely?
• Is there a sandbox, test mode, local mode, preview environment, or dry run?
• What should a human review before production use?

Features

• Fast searchable directory for agent-friendly software.
• Cmd-K style search for tools, categories, and capability signals.
• Category and capability filtering for broad comparisons.
• Tool detail pages with score breakdowns, evidence links, and limitations.
• Public API routes for agents and scripts.
• Read-only MCP-style JSON-RPC endpoint.
• LLM-friendly Markdown exports.
• JSON catalog stored directly in the repo.
• JSON Schema and audit scripts for safer contributions.
• GitHub pull request and agent-prompt submission flow.

Agent-Readiness Signals

The catalog tracks eight normalized signals:

Scoring Model

Scores are out of 100 and are derived from the evidence in each tool record.

The website keeps the score compact. Agent surfaces expose the detailed scoreBreakdown object.

Launch Score Model

launchScore is a secondary ranking signal used after agent readiness. It is computed from launchSignals, not entered directly in catalog records.

Use launchSignals to describe public traction and importance: adoption tier, ecosystem importance, GitHub stars, package download volume, maturity, distribution handling, and an evidence URL. For self-hosted imports, GitHub stars keep the historical formula: min(950, 120 + floor(stars / 150)).

Agent Quick Start

Agents should use these read-only public surfaces. Do not ask for database credentials and do not scrape HTML when skill, MCP, API, OpenAPI, or Markdown surfaces are enough.

Recommended agent workflow:

1. Start with npx canagentsuse@latest setup --all-agents --yes when you can run shell commands.
2. Search for a focused query such as stripe, scraping, email, browser, mcp, or billing.
3. Inspect one tool by slug before recommending it.
4. Compare scoreBreakdown, launchScoreBreakdown, capabilities, evidence URLs, pricing clarity, sandbox support, and limitations.
5. For broad comparisons, fetch the full catalog once and search locally.
6. Mention caution notes before live money movement, production data changes, account creation, infrastructure changes, or irreversible actions.
7. Treat scores as discovery signals, not legal, security, purchasing, or compliance approval.

Use The CLI

Use the CLI when you want one-command agent setup or terminal-first discovery without installing the repo. It calls the same public read-only API that agents use and can replace the older npx skills flow for supported local agents.

npx canagentsuse@latest --help
npx canagentsuse@latest setup
npx canagentsuse@latest setup --all-agents --dry-run
npx canagentsuse@latest setup --all-agents --yes
npx canagentsuse@latest setup --mcp --claude --yes
npx canagentsuse@latest setup --cli --cursor --yes
npx canagentsuse@latest doctor
npx canagentsuse@latest search stripe
npx canagentsuse@latest search "email api" --capability api --limit 5
npx canagentsuse@latest search --capability mcp --json
npx canagentsuse@latest tool stripe
npx canagentsuse@latest mcp-config
npx canagentsuse@latest install-guide --json

Setup targets:

npx canagentsuse@latest setup --claude --yes
npx canagentsuse@latest setup --cursor --yes
npx canagentsuse@latest setup --codex --yes
npx canagentsuse@latest setup --opencode --yes
npx canagentsuse@latest setup --gemini --yes
npx canagentsuse@latest setup --universal --yes

Run bare npx canagentsuse@latest setup in an interactive terminal to choose mode, target, and install location. Agents and scripts should pass explicit flags plus --yes.

Setup defaults to global user config. Use --global to be explicit, or --project to write project-local config such as .mcp.json, .cursor/mcp.json, .codex/config.toml, .gemini/settings.json, or opencode.json. Use --dry-run before writing; the CLI backs up existing config files before editing and only updates the canagentsuse MCP entry.

For scripts and agents, prefer --json:

npx canagentsuse@latest search "billing api" --capability api --limit 10 --json

The default site is https://canagentsuse.com. Override it for previews:

CANAGENTSUSE_SITE_URL=https://www.canagentsuse.com npx canagentsuse@latest catalog --json

Use The Skills

Can Agents Use ships skills.sh-discoverable skills in skills/. The root skills.sh.json groups them for the skills.sh repository page at skills.sh/phuctm97/canagentsuse. The CLI is preferred for local agent setup because it installs both MCP and skills where possible. Use skills.sh as a registry fallback.

List the bundled CLI skills:

npx canagentsuse@latest skills list

Install all bundled skills into all supported agent folders:

npx canagentsuse@latest skills install --all --all-agents --yes

skills.sh fallback list command:

npx skills add phuctm97/canagentsuse --list

skills.sh fallback install all:

npx skills add phuctm97/canagentsuse

skills.sh fallback install one focused skill:

npx skills add phuctm97/canagentsuse --skill find-mcp-tools

Manual fallback for agents that read local skill folders:

mkdir -p ~/.codex/skills/can-agents-use
curl -fsSL https://canagentsuse.com/skill.md \
  -o ~/.codex/skills/can-agents-use/SKILL.md

The /skill.md fallback exposes the umbrella skill. Use the CLI when you want the full multi-skill folder copied into local agent directories.

Use MCP

Use the read-only MCP endpoint when your agent can call remote MCP tools.

{
  "mcpServers": {
    "canagentsuse": {
      "type": "http",
      "url": "https://canagentsuse.com/api/mcp"
    }
  }
}

Available MCP tools:

MCP resources:

MCP smoke test:

curl -fsS -X POST https://canagentsuse.com/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Search over MCP:

curl -fsS -X POST https://canagentsuse.com/api/mcp \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search_agent_tools",
      "arguments": {
        "query": "stripe",
        "page": 1,
        "limit": 10
      }
    }
  }'

Fetch one tool over MCP:

curl -fsS -X POST https://canagentsuse.com/api/mcp \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_agent_tool",
      "arguments": {
        "slug": "stripe"
      }
    }
  }'

Search defaults to page 1 and limit 10; limit maxes at 50. Keep queries under 120 characters and avoid polling loops.

Use The HTTP API

Use these endpoints when an agent or script prefers plain HTTP JSON.

Search parameters:

Examples:

curl -fsS 'https://canagentsuse.com/api/agent/install'
curl -fsS 'https://canagentsuse.com/api/agent/search?q=stripe&page=1&limit=10'
curl -fsS 'https://canagentsuse.com/api/agent/search?capability=mcp&limit=20'
curl -fsS 'https://canagentsuse.com/api/agent/catalog'
curl -fsS 'https://canagentsuse.com/api/agent/tools/github'
curl -fsS 'https://canagentsuse.com/openapi.json'

For broad comparisons, prefer one /api/agent/catalog request over paging through every search result.

Use Markdown Context

Use Markdown surfaces when an agent needs plain text context instead of JSON.

Examples:

curl -fsS https://canagentsuse.com/llms.txt
curl -fsS https://canagentsuse.com/llms-full.txt
curl -fsS https://canagentsuse.com/skill.md

Data Is The Product

The repo is intentionally file-backed. There is no database required to run, build, or contribute.

• data/tools: canonical one-file-per-tool catalog source.
• data/taxonomy.json: shared categories, capabilities, and use cases.
• data/catalog.schema.json: validation schema for editors and agents.
• data/README.md: data format notes.

data/catalog.json is generated locally from those split sources for Next.js, APIs, MCP responses, and LLM-facing exports. Do not edit or commit it. Markdown is kept for documentation.

Repository Layout

This repo is a Bun workspace monorepo with two packages:

Project assets stay at the root so GitHub readers and agents can find them quickly:

• data/tools: canonical catalog records, split by first slug character.
• data/taxonomy.json: canonical shared taxonomy.
• skills/: skills.sh-discoverable skills.
• skills.sh.json: skills.sh metadata.
• .github/PULL_REQUEST_TEMPLATE/add-tool.md: new-tool contribution template.
• .github/PULL_REQUEST_TEMPLATE/update-tool.md: existing-tool update template.

Example Tool Shape

{
  "slug": "stripe",
  "name": "Stripe",
  "websiteUrl": "https://stripe.com",
  "docsUrl": "https://docs.stripe.com",
  "mcpServer": "https://mcp.stripe.com",
  "categorySlugs": ["billing-payments"],
  "useCaseSlugs": ["charge-a-customer"],
  "capabilities": [
    {
      "slug": "api",
      "supportLevel": "native",
      "detail": "REST API covers payments, billing, customers, webhooks, and reporting.",
      "evidenceUrl": "https://docs.stripe.com/api"
    }
  ]
}

Local Development

bun install
bun run dev

Open http://localhost:60139.

Website-specific env examples live in packages/website/.env.example. Put local website env in packages/website/.env.local.

Useful checks:

bun run catalog:build
bun run catalog:audit
bun run cli:test
bun run cli:pack
bun run build

Run every main repo check:

bun run check

Deploy The Website

The Vercel project should deploy the website package from this monorepo:

Keep these env vars on the Vercel website project:

NEXT_PUBLIC_SITE_URL="https://canagentsuse.com"
NEXT_PUBLIC_OG_ASSET_URL="https://canagentsuse.vercel.app"

Release With Changesets

Releases are driven by committed Changesets in .changeset. A changeset is the version plan file for one or both packages.

Create a release plan:

bun run changeset

Use these package names:

Release is manual-only. Every commit to main runs the Main Validate workflow. After one or more version plans are committed to main, wait for the latest Main Validate run for that exact commit to pass. Then open the GitHub Actions tab, select the Release workflow, and run it from the GitHub UI. The release preflight rejects the run when the latest completed Main Validate run for main is missing, failed, or belongs to a different commit.

1. Checks that the latest Main Validate run passed for the current main commit.
2. Reads all changeset files and detects which packages need release.
3. Runs changeset version to update package versions and changelogs.
4. Syncs the CLI runtime version constant from packages/cli/package.json.
5. Pushes the version commit back to main.
6. Runs catalog, CLI, package, and website build checks on the versioned tree.
7. Publishes canagentsuse to npm if the CLI package is in the plan.
8. Deploys @canagentsuse/website if the website package is in the plan.
9. Pushes package tags back to main.

GitHub release notes are written by the Release workflow instead of GitHub’s default generated notes. The release feed should use one What's Changed section containing the CLI publish notice, website deploy notice, and every PR or direct commit in the release. Do not add an Other Changes section. Add a New Contributors section only for authors whose first merged PR is included in that release.

The CLI publish path is set up for npm Trusted Publishing through GitHub Actions OIDC, so no long-lived npm token is required when npm trusted publishing is configured. An optional NPM_TOKEN secret is still supported as a fallback.

Optional Vercel secrets for explicit GitHub Actions deploys:

VERCEL_TOKEN
VERCEL_ORG_ID
VERCEL_PROJECT_ID

If those Vercel secrets are not set, the workflow still pushes the version commit; a connected Vercel Git integration can deploy that commit normally.

Contributing

The best contribution is a well-evidenced catalog record. New tools and existing-tool updates both go through pull requests, but they use separate templates and skills.

1. Search first by name, slug, domain, GitHub repo, and package name. Update an existing record instead of adding a duplicate.
2. Add or edit exactly one tool file in data/tools, for example data/tools/s/stripe.json.
3. Optionally add a custom SVG logo at packages/website/public/logos/tools/.svg, using the exact stable slug as the filename. For example, Stripe would use packages/website/public/logos/tools/stripe.svg.
4. If adding a custom SVG logo, set logoPath in the tool JSON to /logos/tools/.svg; for Stripe, use "logoPath": "/logos/tools/stripe.svg". If no logo is added, omit logoPath so the website can fall back to Simple Icons, favicon, or initials.
5. Add evidence URLs that match each claim: API docs for API claims, package docs or registry for CLI/MCP claims, pricing page for pricing claims.
6. Add every launchSignals key from honest public evidence. Use exact public star/download counts when available, null for unavailable numeric signals, and conservative enum values rather than inflated traction.
7. Include limitation notes for anything that affects money, production data, infrastructure, or users.
8. Run bun run catalog:build, bun run catalog:format, and bun run catalog:audit.
9. Add one or more .changeset/*.md version plans when the change should release the website or CLI.
10. Do not edit package files, lockfiles, changelogs, workflows, repo scripts, app code, agent skills, version bumps, or release workflow files manually. The manual Release workflow handles version commits from committed changesets.
11. Open a pull request. The Catalog PR workflow rebuilds the generated catalog, reruns the formatter, audits metadata, and typechecks catalog consumers.

If you are not ready to edit JSON, use the homepage Submit menu or command search to open a new-tool PR template or copy a ready-to-run submit prompt. For existing tools, use the actions on the tool detail page to open an update PR template or copy the matching update prompt.

Tech Stack

• Next.js 16 App Router
• React 19
• TypeScript
• Tailwind CSS 4
• shadcn/ui
• Bun
• Static JSON data

Project Goal

Make the GitHub repo and the domain the two canonical ways to discover, inspect, and improve the catalog. The website should be the fastest way to search. The README should be the fastest way to understand why the repo is worth starring, forking, and improving.