# MCP Tool Schema Auditor — AgentReady (`matdavis/agentready-mcp-tool-auditor`) Actor

Get a 0–100 MCP tool-schema score in seconds. Leave input empty to see a built-in sample, or audit a public HTTPS endpoint, an Apify Connector, or pasted tools/list JSON—without executing upstream tools.

- **URL**: https://apify.com/matdavis/agentready-mcp-tool-auditor.md
- **Developed by:** [Davis](https://apify.com/matdavis) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.05 / completed server audit

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## MCP Tool Schema Auditor — AgentReady

> Check your MCP tool metadata before your next release.

Catch broken schemas, vague tool descriptions, risky permissions, and token bloat before production. AgentReady returns a `0–100` readiness score, prioritized findings, and concrete remediation guidance in seconds.

- Catch tools that agents cannot reliably discover or call.
- Surface destructive side effects and permission risks before users do.
- Find oversized schemas and the tools consuming the most context.
- Use stable finding codes in CI to block risky releases.
- Export machine-readable JSON and a human-readable Markdown report.

**No LLM calls. No upstream tool execution. Metadata only.**

### Try it in 10 seconds — no input required

1. Click **Try for free**.
2. Leave all three sources empty and start the audit.
3. Inspect the default dataset for JSON and the key-value store for `REPORT.md`.

The built-in read-only sample makes this a zero-setup preview; it does not inspect your server. When you are ready, use a public HTTPS endpoint, an authorized connector, or your `tools/list` array below.

### Check your own server

Use this when you add or change MCP tools and want to review schema mistakes, unclear descriptions, side-effect hints, or schema size. You receive a JSON report and, by default, a Markdown report with findings and suggested fixes.

1. Open **Try for free** and choose the JSON input editor.
2. Replace the input with the following example, changing the URL to your public HTTPS Streamable HTTP MCP endpoint:

```json
{
  "mcpServerUrl": "https://mcp.deepwiki.com/mcp",
  "includeMarkdown": true
}
```

3. Start the audit. Open the output dataset for JSON, or the run's key-value store for `REPORT.md`.

Use exactly one source: a URL, an authorized connector, or a `tools` array. If you have a previously saved input, remove its sample `tools` array before entering a URL. For local/stdio servers, paste their `tools/list` array into `tools`; do not expose a local service just to audit it. An empty input runs the built-in demonstration and does not inspect your server.

The hosted price is **$0.05 per completed audit**; the Store's trial button does not mean unlimited free audits. A 100 score means no current rule was triggered, not a runtime safety certificate.

### What it checks

| Area | Checks |
| --- | --- |
| Contract | MCP-safe names, object input schemas, valid `required`, parameter descriptions, numeric bounds, categorical enums, array limits |
| Discoverability | Ambiguous tool names, weak descriptions, semantically overlapping tools, oversized tool surfaces |
| Context cost | Per-tool and whole-server character-based token estimates, top context consumers, high-overhead warnings |
| Authority | Read-only, write, destructive, and credential-sensitive classification |
| Safety | Side-effect disclosure, read-only conflicts, destructive-tool escalation |
| Permission design | MCP annotation coverage and recommended runtime policy |

### Public server snapshots — September 8, 2026

We queried `tools/list` on two public MCP services and ran AgentReady locally against their returned metadata. No upstream tools were executed.

| Service / reported version | Tools | Score | Findings | Estimated schema tokens |
| --- | ---: | ---: | ---: | ---: |
| DeepWiki 2.14.3 | 3 | 100/100 | 0 | 379 |
| Context7 4.0.5 | 2 | 100/100 | 0 | 1,215 |

A clean report means these metadata snapshots triggered none of the current rules. It does not certify runtime safety, correctness, or model performance. Token counts use four characters per token; the two services expose different capabilities and this is not a quality ranking. These are independent observations, not customer endorsements.

To audit the current DeepWiki metadata, use this input (a hosted audit uses the pricing below):

```json
{
  "mcpServerUrl": "https://mcp.deepwiki.com/mcp",
  "includeMarkdown": true
}
```

Endpoint references: [DeepWiki documentation](https://docs.devin.ai/work-with-devin/deepwiki-mcp) and [Context7 project](https://github.com/upstash/context7). Live results can change as the services evolve.

### Deliberately flawed fixture — finding and fixing issues

The bundled two-tool fixture scores **59/100** and produces **2 critical, 2 high, 4 medium, and 1 low** finding. The highest-priority fixes are immediately actionable:

- `DESTRUCTIVE_HINT_MISSING` — mark the destructive tool and require human approval.
- `SIDE_EFFECT_UNDECLARED` — state what the operation changes and whether it is reversible.
- `REQUIRED_PROPERTY_UNKNOWN` — define the required `id` property or remove it from `required`.
- `TOOL_NAME_AMBIGUOUS` — replace `delete` with a specific verb-resource name such as `delete_calendar_event`.

This example is generated from [`examples/input-tools.json`](examples/input-tools.json), not a mocked marketing score.

### How it works

1. Run once with no input to see the built-in sample, or provide one source: an Apify MCP Connector, a public HTTPS MCP endpoint, or a raw `tools/list` array.
2. AgentReady statically audits schema quality, discoverability, context cost, authority, safety, and permission design.
3. Review the score, five dimension scores, severity-ranked findings, evidence, and remediation suggestions.
4. Save the JSON or Markdown report for CI, baselining, or release review.

### Input modes

Choose one source, or leave all three empty for the built-in sample:

1. `mcpConnector` — an authorized Apify MCP Connector. This is the preferred option for OAuth or private credentials because AgentReady only receives the connector ID; Apify injects the credential at its proxy.
2. `mcpServerUrl` — a public HTTPS Streamable HTTP endpoint. Optional headers are accepted as encrypted Actor input. Localhost, private IP ranges, URL credentials, and redirects are blocked.
3. `tools` — the raw tool array returned by MCP `tools/list`. This is ideal for local/stdio servers and CI fixtures.

For a zero-setup preview, leave all three sources empty. AgentReady audits one built-in read-only sample tool so the default Store run always produces a report.

### Use from an MCP client

Expose AgentReady directly as a tool through the official Apify MCP server:

```json
{
  "mcpServers": {
    "agentready": {
      "url": "https://mcp.apify.com?tools=matdavis/agentready-mcp-tool-auditor"
    }
  }
}
```

The MCP client will request Apify authentication before it can run the Actor or read its output.

Minimal inline input:

```json
{
  "tools": [
    {
      "name": "get_weather",
      "description": "Return the current weather for one city without changing external state.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "City name and optional country code."
          }
        },
        "required": ["city"],
        "additionalProperties": false
      },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true
      }
    }
  ]
}
```

A deliberately flawed example is available at [`examples/input-tools.json`](examples/input-tools.json).

### Output shape

```json
{
  "schemaVersion": "1.0",
  "source": { "kind": "inline", "label": "Inline tools" },
  "summary": {
    "score": 72,
    "tools": 23,
    "critical": 2,
    "high": 4,
    "estimatedSchemaTokens": 12400,
    "contextOverhead": "HIGH"
  },
  "scores": {
    "contract": 85,
    "discoverability": 64,
    "tokenEfficiency": 51,
    "safety": 68,
    "permissionDesign": 71
  },
  "risks": [],
  "tokenUsage": [],
  "findings": []
}
```

The default dataset and `REPORT` key contain the complete JSON report. `REPORT.md` contains the human-readable report when `includeMarkdown` is enabled.

### Pricing

`$0.05` per completed server audit. The charge is emitted only after the audit reports have been saved successfully.

### Scoring model

Each finding deducts points from one dimension according to severity. The overall score uses:

| Dimension | Weight |
| --- | ---: |
| Contract | 25% |
| Discoverability | 20% |
| Token efficiency | 15% |
| Safety | 25% |
| Permission design | 15% |

The rules are intentionally explainable. Every deduction has a stable code, severity, evidence/location where available, and a concrete remediation.

### CI usage

Set `failOnSeverity` to `critical`, `high`, `medium`, or `low`. AgentReady writes the report first and then fails the run if the selected threshold is met, allowing a pipeline to retain evidence while blocking a release.

Stable rule codes make the report suitable for baselining and diffing.

### Security boundaries

- AgentReady requests metadata only; it never calls upstream tools.
- Connector credentials remain behind the Apify MCP proxy.
- Direct URL mode accepts HTTPS only and blocks obvious SSRF targets and redirects.
- Header values are never copied into reports or logs.
- Risk labels are static heuristics, not a substitute for runtime authorization, approval, sandboxing, or audit logs.
- Tool annotations are untrusted hints. A runtime policy engine must independently enforce authority.

### Current MVP limits

- Token estimates use configurable characters-per-token rather than a model-specific tokenizer.
- Risk detection is English-oriented and based on names, descriptions, and MCP annotations.
- The Actor audits contracts only; it does not execute test calls or verify real-world reversibility/idempotency.
- OAuth is supported through Apify MCP Connectors, not a custom interactive OAuth flow.
- DNS checks reduce SSRF risk but should be reviewed and hardened before exposing unrestricted direct URL mode at scale.

### Local development

Requirements: Node.js 22+.

```bash
npm install
npm test
npm run build
```

To run as a local Actor, place an input document in the local default key-value store or use the Apify CLI, then run:

```bash
npm start
```

### License

MIT

# Actor input Schema

## `mcpConnector` (type: `string`):

Safest option for authenticated servers. Credentials stay in Apify and are injected by its MCP proxy.

## `mcpServerUrl` (type: `string`):

A public Streamable HTTP MCP endpoint. HTTPS is required; localhost and private IP ranges are blocked.

## `headers` (type: `array`):

Optional headers for the public endpoint, for example Authorization. Stored as secret input.

## `tools` (type: `array`):

Paste the tools array from tools/list when the server cannot be reached remotely.

## `charsPerToken` (type: `integer`):

Portable token estimate ratio. Use a model-specific tokenizer in a future deep-audit version.

## `includeMarkdown` (type: `boolean`):

Store a human-readable REPORT.md in addition to structured JSON.

## `failOnSeverity` (type: `string`):

Optionally fail the Actor run when a finding at or above this severity is detected.

## Actor input object example

```json
{
  "charsPerToken": 4,
  "includeMarkdown": true,
  "failOnSeverity": "none"
}
```

# Actor output Schema

## `results` (type: `string`):

JSON report in the default dataset.

## `jsonReport` (type: `string`):

Complete report as a key-value store record.

## `markdownReport` (type: `string`):

Human-readable report when includeMarkdown is enabled.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("matdavis/agentready-mcp-tool-auditor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("matdavis/agentready-mcp-tool-auditor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call matdavis/agentready-mcp-tool-auditor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,matdavis/agentready-mcp-tool-auditor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/35QdauDiUqebPqoWi/builds/W7y1kbpTlhVMfpiEz/openapi.json