# How to Track Agent Recommendations Across API, SDK, CLI, and MCP

Your API might rank #1 while your CLI is invisible. Here's how to measure visibility across all 4 surfaces coding agents use to discover developer tools.

**Published:** 2026-08-30
**Updated:** 2026-08-30
**Category:** Guides
**Author:** Jun Liang Lee
**Read time:** 12 min read

**Your API ranks #3 in Claude Code. Your CLI doesn't exist on the leaderboard. Your MCP server is broken.**

That's what we found when we started tracking developer tools across multiple surfaces. Most companies optimize their REST API and assume the work is done. They're missing three other discovery channels - and losing to competitors who figured this out.

In our [benchmark of 70+ APIs](/blog/we-tested-50-apis-in-coding-agents), the winners weren't the best-documented APIs. They were the ones with presence across **multiple agent touchpoints**: API, SDK, CLI, and MCP.

Here's how to track and measure each one.

---

## TL;DR: The 4 Surfaces

| Surface | What Agents Do                   | Coverage in Our Benchmark   | Key Metric              |
| ------- | -------------------------------- | --------------------------- | ----------------------- |
| **API** | Generate `fetch()` or SDK calls  | 73/73 APIs tested           | Tool call success rate  |
| **SDK** | `npm install` + import library   | Most APIs have SDKs         | Import accuracy         |
| **CLI** | Execute shell commands           | Only 31/73 have CLI support | JSON output support     |
| **MCP** | Connect directly, no code needed | ~20 functional MCP servers  | Connection success rate |

**The insight:** Daytona went from lower rankings to #1 in sandboxes by shipping better tooling across all surfaces. The top performers covered multiple touchpoints. Single-surface optimization leaves gaps competitors exploit.

---

## Why Track All Four Surfaces?

When a developer asks Claude Code to "deploy my app," the agent picks from available options:

1. **Does the tool have an MCP server?** → Use it directly (fastest)
2. **Does the tool have a CLI?** → Execute shell commands
3. **Does the tool have an SDK?** → Generate import + method calls
4. **Fallback:** Generate raw API calls

If you only have an API, you're the fallback option. Competitors with CLI or MCP presence get recommended first because agents can complete tasks faster and more reliably.

### The Data

From our benchmark:

- **CLI with `--json` flag**: +18 points average score improvement
- **Functional MCP server**: Category dominance (Chroma, Qdrant own vector databases via MCP)
- **Multiple surfaces**: Top 10 APIs averaged 2.7 surfaces; bottom 10 averaged 1.2

The gap is real and measurable.

---

## Surface #1: API Endpoints

The baseline. Every developer tool has API endpoints. But "having an API" doesn't mean agents can use it well.

### What Agents Actually Do

```typescript
// Claude Code generates this
const response = await fetch("https://api.acme.com/v1/users", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ACME_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "user@example.com" }),
});

const data = await response.json();
```

The agent needs to know: endpoint URL, auth pattern, request shape, response shape. Get any of these wrong and the code fails.

### What to Track

| Metric                    | Good                      | Needs Work                          | How to Check                                     |
| ------------------------- | ------------------------- | ----------------------------------- | ------------------------------------------------ |
| **Recommendation rate**   | 40%+ for your category    | Under 15%                           | Ask Claude Code "[use case] for my app" 10 times |
| **Endpoint accuracy**     | Correct URL, method, path | Wrong version, deprecated endpoints | Review generated code                            |
| **Auth pattern accuracy** | Correct header format     | Missing auth, wrong key format      | Check if code runs                               |
| **Tool call success**     | 80%+                      | Under 50%                           | Execute generated code with real API key         |

### Benchmark Data: API Speed Variance

From our Codex tests:

| API           | Time to Complete | Tool Calls |
| ------------- | ---------------- | ---------- |
| **Firecrawl** | 49 seconds       | 6          |
| **Jina AI**   | 1m 12s           | 8          |
| **Stripe**    | 2m 45s           | 14         |
| **Circle**    | 43 minutes       | 129        |

50x speed difference. The slow APIs had unclear error messages, inconsistent response shapes, and complex auth flows that agents struggled to navigate.

### Common Failures

**Wrong endpoint versions:**

```typescript
// Agent generates v1 (from training data)
fetch("https://api.acme.com/v1/users");

// Your current API is v3
fetch("https://api.acme.com/v3/users");
```

**Deprecated auth patterns:**

```typescript
// Agent uses API key (old pattern)
headers: { 'X-API-Key': apiKey }

// You now require Bearer token
headers: { 'Authorization': `Bearer ${apiKey}` }
```

**Ambiguous error handling:**

```typescript
// Agent can't recover from this
if (!response.ok) throw new Error("Request failed");

// Agent can recover from this
if (!response.ok) {
  const error = await response.json();
  throw new Error(`${error.code}: ${error.message}`);
}
```

### How to Improve API Visibility

1. **Add llms.txt** with current endpoint patterns:

```txt
# Acme API

## Authentication
Bearer token in Authorization header.
Format: Authorization: Bearer YOUR_API_KEY

## Key Endpoints
POST /v3/users - Create user
GET /v3/users/{id} - Get user
DELETE /v3/users/{id} - Delete user

## Common Errors
401: Invalid API key. Check the key starts with "ak_"
429: Rate limited. Retry after the Retry-After header value
```

2. **Return descriptive errors** - "Invalid API key format. Expected: ak_live_xxx or ak_test_xxx" beats "Error 401"

3. **Keep quick-start code current** - The first code example agents find should work without modification

---

## Surface #2: SDKs and Packages

Agents prefer SDKs over raw API calls. Typed methods with autocomplete are easier to generate correctly than manual fetch requests.

### What Agents Actually Do

```typescript
// Agent installs and imports
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

// Typed method call - agent knows the shape
const message = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }],
});
```

The SDK provides structure. The agent doesn't need to remember endpoint URLs or construct headers manually.

### What to Track

| Metric                     | Good                            | Needs Work                             |
| -------------------------- | ------------------------------- | -------------------------------------- |
| **Package recommendation** | Agent uses SDK, not raw fetch   | Agent writes manual API calls          |
| **Correct package name**   | Uses official @acme/sdk         | Uses old or unofficial package         |
| **Import accuracy**        | Correct import path and syntax  | Wrong named exports, default confusion |
| **Method accuracy**        | Correct method names and params | Hallucinated methods, wrong signatures |

### Benchmark Data: SDK vs Raw API

In our tests, APIs with well-maintained SDKs had:

- **23% higher tool call success rate** than raw-API-only tools
- **Fewer error recovery loops** - typed responses help agents self-correct
- **Faster completion times** - less trial-and-error

### Common Failures

**Wrong package name:**

```typescript
// Agent generates (from training data)
import { Client } from "acme";

// Your current package
import { AcmeClient } from "@acme/sdk";
```

**Incorrect imports:**

```typescript
// Agent writes
import Acme from "@acme/sdk";

// Your SDK uses named exports
import { Acme } from "@acme/sdk";
```

**Hallucinated methods:**

```typescript
// Agent invents a method that doesn't exist
await client.users.findByEmail("user@example.com");

// Your actual method
await client.users.list({ email: "user@example.com" });
```

### How to Improve SDK Visibility

1. **Publish TypeScript definitions** - Agents use types to infer method signatures

2. **Use consistent, memorable package names:**

```txt
## SDKs
- JavaScript: npm install @acme/sdk
- Python: pip install acme-sdk
- Go: go get github.com/acme/sdk-go
```

3. **Keep README examples current and copy-paste ready:**

```typescript
// Install
npm install @acme/sdk

// Initialize
import { AcmeClient } from '@acme/sdk';
const client = new AcmeClient({ apiKey: process.env.ACME_API_KEY });

// Use
const result = await client.doThing({ param: 'value' });
console.log(result.id);
```

4. **Document breaking changes prominently** - Agents using training data may have old patterns

---

## Surface #3: Command-Line Interface

The biggest gap in the ecosystem. **Only 31 out of 73 APIs** in our benchmark have CLI support. The ones that do score significantly higher.

### What Agents Actually Do

```bash
# Agent executes directly in terminal
acme auth login --api-key $ACME_API_KEY
acme projects create --name "my-project" --json
acme deploy ./dist --project my-project
```

No code generation. No imports. Direct execution. When CLIs work well, agents prefer them for automation tasks.

### What to Track

| Metric               | Good                                 | Needs Work                              |
| -------------------- | ------------------------------------ | --------------------------------------- |
| **CLI discovery**    | Agent knows CLI exists               | Agent writes SDK code instead           |
| **Command accuracy** | Correct subcommands and flags        | Wrong flags, missing required args      |
| **Output parsing**   | Agent extracts data from JSON output | Agent can't parse human-readable tables |
| **Auth completion**  | Non-interactive auth works           | Agent stuck at "Enter password:" prompt |

### Benchmark Data: CLI Impact

| Factor                                 | Score Impact       |
| -------------------------------------- | ------------------ |
| Has CLI                                | +12 points average |
| CLI with `--json` flag                 | +18 points average |
| CLI with non-interactive auth          | +15 points average |
| CLI in package managers (brew, npm -g) | +8 points average  |

**CLI leaders by category:**

- **Sandboxes:** Daytona, Vercel
- **Auth:** WorkOS, Auth0
- **Search:** Firecrawl, Jina AI

### Common Failures

**Interactive prompts:**

```bash
# Agent runs
acme deploy

# CLI prompts (agent can't respond)
? Select environment: (use arrow keys)
❯ production
  staging
  development
```

**No JSON output:**

```bash
# Agent runs
acme projects list

# CLI returns human-readable table (hard to parse)
┌──────────┬─────────────┬──────────┐
│ ID       │ Name        │ Status   │
├──────────┼─────────────┼──────────┤
│ proj_123 │ my-project  │ active   │
└──────────┴─────────────┴──────────┘

# Agent needs
acme projects list --json
# Returns: [{"id":"proj_123","name":"my-project","status":"active"}]
```

**Complex auth flows:**

```bash
# Agent runs
acme login

# CLI opens browser for OAuth (agent can't complete)
Opening browser for authentication...
Waiting for callback...
```

### How to Make Your CLI Agent-Friendly

1. **Add `--json` flag to every command** - This is the single highest-impact change

2. **Support non-interactive mode:**

```bash
# Accept all defaults
acme deploy --yes

# Skip confirmations
acme delete --force

# Provide all inputs via flags
acme create --name "my-project" --type api --region us-east-1
```

3. **Support API key auth via environment variable:**

```bash
export ACME_API_KEY=ak_live_xxx
acme projects list  # Works without login flow
```

4. **Document CLI in llms.txt:**

```txt
## CLI
Install: npm install -g @acme/cli
Auth: export ACME_API_KEY=your_key (or --api-key flag)

## Common Commands
acme projects list --json
acme projects create --name NAME --json
acme deploy ./dist --project PROJECT_ID --json

All commands support --json for machine-readable output.
```

---

## Surface #4: MCP Servers

The Model Context Protocol lets agents connect directly to your service. No code generation, no CLI parsing - direct tool calls.

### What Agents Actually Do

```
User: Create a new project called "my-app"

[MCP] Connecting to acme-server...
[MCP] Connected

[Tool Call] acme.createProject
  Arguments: { "name": "my-app" }

[Tool Result]
  { "id": "proj_456", "name": "my-app", "status": "created", "url": "https://my-app.acme.dev" }
```

The agent didn't write code. It called your MCP tool directly and got structured results. This is the fastest path to task completion.

### What to Track

| Metric                 | Good                          | Needs Work                      |
| ---------------------- | ----------------------------- | ------------------------------- |
| **Registry presence**  | Listed in MCP registries      | Agent doesn't know it exists    |
| **Connection success** | Connects reliably             | Connection errors, timeouts     |
| **Tool call success**  | Tools return expected results | Schema mismatches, errors       |
| **Coverage**           | Key workflows available       | Only exposes subset of features |

### Benchmark Data: MCP Performance

| MCP Server   | Time to Complete | Tool Calls | Notes            |
| ------------ | ---------------- | ---------- | ---------------- |
| **Exa**      | 1m 28s           | 6          | Fastest MCP      |
| **Tavily**   | 2m 15s           | 9          | Search leader    |
| **Chroma**   | 3m 02s           | 12         | Vector DB leader |
| **Coinbase** | 39m 5s           | 79         | Slowest MCP      |

Most MCP servers we tested were barely functional - broken tool definitions, missing auth, incomplete coverage. But the ones that worked dominated their categories completely.

### MCP Leaders by Category

| Category             | Leaders                    | Why They Win                            |
| -------------------- | -------------------------- | --------------------------------------- |
| **Vector Databases** | Chroma, Qdrant             | Full CRUD via MCP, reliable connections |
| **Search**           | Tavily, Jina AI, Firecrawl | Fast, typed responses                   |
| **Email**            | AgentMail (YC S25)         | Direct send/receive, no SDK needed      |
| **Auth**             | Descope, Clerk             | User management via tools               |
| **Payment**          | Stripe, PayPal             | Charges and subscriptions via MCP       |
| **Voice AI**         | ElevenLabs, Deepgram       | TTS/STT directly callable               |
| **Sandboxes**        | Daytona                    | Deploy and manage without CLI           |

### Common Failures

**Not in registries:**

```
User: Create a database in Acme

Claude Code: I don't see an MCP server for Acme. Let me write code to use their API instead...
```

**Broken tool definitions:**

```
[Tool Call] acme.createProject
  Arguments: { "name": "my-app" }

[Error] Tool schema expects "projectName", not "name"
```

**Missing authentication:**

```
[Tool Call] acme.listProjects

[Error] 401 Unauthorized - No API key configured
```

### How to Build an Agent-Friendly MCP Server

1. **Publish to the [MCP server registry](https://github.com/modelcontextprotocol/servers)** - This is how agents discover you

2. **Test every tool definition:**

```typescript
// Tool schema must match actual behavior
{
  name: "createProject",
  description: "Create a new project",
  inputSchema: {
    type: "object",
    properties: {
      name: { type: "string", description: "Project name" },
      region: { type: "string", enum: ["us-east-1", "eu-west-1"] }
    },
    required: ["name"]
  }
}
```

3. **Support API key via environment variable:**

```bash
# User sets this once
export ACME_API_KEY=ak_live_xxx

# MCP server reads it automatically
```

4. **Cover your top 3 use cases first** - Don't try to expose your entire API surface. Focus on what developers actually do.

---

## Tracking All Four Surfaces: The Unified View

Tracking each surface manually doesn't scale. Here's what to measure in one dashboard:

### Cross-Surface Scorecard

| Metric                  | API | SDK  | CLI  | MCP  |
| ----------------------- | --- | ---- | ---- | ---- |
| **Exists?**             | ✅  | ✅   | ❌   | ❌   |
| **Agent discovers it?** | 67% | 45%  | -    | -    |
| **Success rate**        | 72% | 81%  | -    | -    |
| **vs Competitor A**     | Win | Lose | Lose | Lose |
| **vs Competitor B**     | Win | Win  | Lose | Lose |

This company has strong API and SDK presence but is losing on CLI and MCP - exactly where Competitor A is winning.

### What Lightsage Tracks

Lightsage provides unified tracking across all four surfaces:

- **[API Leaderboard](https://lightsage.com/leaderboard/claudecode/api)** - Endpoint visibility and tool call success
- **[CLI Leaderboard](https://lightsage.com/leaderboard/claudecode/cli)** - Command-line tool rankings and JSON support
- **[MCP Leaderboard](https://lightsage.com/leaderboard/claudecode/mcp)** - Model Context Protocol server rankings
- **[Codex Leaderboard](https://lightsage.com/leaderboard/codex/api)** - OpenAI Codex-specific behavior (often differs from Claude Code)

The platform identifies which surface you're weakest on and prioritizes fixes.

---

## The Priority Matrix

Where to invest based on your current state:

| Your Situation                   | Highest-Impact Action                    | Time      | Expected Gain                 |
| -------------------------------- | ---------------------------------------- | --------- | ----------------------------- |
| No agent presence                | Add llms.txt + fix robots.txt            | 1 hour    | Baseline visibility           |
| API-only, competitors have CLI   | Build CLI with `--json`                  | 1-2 days  | +18 points average            |
| Good API/SDK, no MCP             | Build MCP server for top 3 workflows     | 1-2 weeks | Category leadership potential |
| Present everywhere, still losing | Analyze per-surface metrics, fix weakest | Varies    | Close competitive gaps        |

### Quick Wins by Surface

**API (30 minutes)**

- Add llms.txt with current endpoints and auth
- Fix robots.txt to allow ClaudeBot, GPTBot
- Update quick-start code to current patterns

**SDK (2-4 hours)**

- Add TypeScript definitions if missing
- Update README with copy-paste examples
- Ensure package name is consistent across languages

**CLI (1-2 days)**

- Add `--json` flag to all commands
- Add `--yes` flag for non-interactive mode
- Support `ACME_API_KEY` environment variable

**MCP (1-2 weeks)**

- Build server covering top 3 use cases
- Test all tool definitions against actual behavior
- Publish to MCP registry

---

## FAQ

### Do I need all four surfaces?

No. Start with API + SDK - that's where most interactions happen. Add CLI if your tool is used in automation or DevOps. Add MCP if you want the best agent experience and can maintain it.

### Which surface matters most?

Depends on the use case:

- **One-off integrations**: SDK preferred
- **Automation/scripting**: CLI preferred
- **Interactive tasks**: MCP preferred
- **Fallback**: Raw API calls

Agents pick the most reliable path available. If you only have an API, you're always the fallback.

### My CLI works for humans but breaks for agents. Why?

Three common issues:

1. **Interactive prompts** - Agents can't answer "Are you sure?"
2. **No JSON output** - Agents struggle to parse tables
3. **OAuth flows** - Agents can't complete browser redirects

Add `--json`, `--yes`, and API key auth to fix all three.

### How do I know which surface is hurting me?

Compare your rankings across the four Devtool Arena leaderboards. If you're #5 on API but don't appear on CLI or MCP, that's your gap.

### How often should I track each surface?

- **Weekly**: Spot-check your primary surface
- **Monthly**: Full audit across all four
- **After releases**: Re-test any surface you changed

---

## Related Reading

- [We Tested 70+ APIs in Claude Code and Codex](/blog/we-tested-50-apis-in-coding-agents) - The benchmark data behind these recommendations
- [How Coding Agents Actually Decide Which SDK to Use](/blog/how-coding-agents-decide-which-sdk-to-use) - The 4-layer decision stack
- [Why Claude Code Isn't Recommending Your Library](/blog/why-claude-code-not-recommending-your-library) - The 4 fixable reasons
- [How to Track AI Recommendations for Your API](/blog/how-to-track-ai-recommendations-for-your-api) - Step-by-step setup for answer engine + coding agent tracking
- [The Devtool Visibility Stack in 2026](/blog/devtool-visibility-stack-2026) - The measurement framework for API teams

---

## Start Tracking All Four Surfaces

Your API might be winning while your CLI loses. Your SDK might be strong while your MCP is broken. Single-surface tracking hides these gaps.

**Free:** [Check the Devtool Arena leaderboards](https://lightsage.com/leaderboard) - see your ranking across API, CLI, MCP, and Codex.

**Full tracking:** [Get Lightsage access](https://lightsage.com/welcome) - unified dashboard tracking all four surfaces across 12 coding agents.

**Community:** Join the [AI DevTool Demo Night](https://luma.com/devtooldemo5) - 15,000+ developer community, 50+ DevTool companies, hosted at AWS SF.