Remote MCP discovery

Grep exposes research as an MCP server.

Agents can discover the public v2 MCP endpoint, negotiate OAuth through protected-resource metadata, and call focused tools for research jobs, files, attachments, quota, and billing.

Server CardOAuth metadataOAuth guide
/.well-known/mcp/server-card.jsonMCP 2025-06-18
json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json",
  "version": "1.0",
  "protocolVersion": "2025-06-18",
  "serverInfo": {
    "name": "grep-public-api-v2",
    "title": "Grep Public API v2 MCP",
    "version": "1.0.0"
  },
  "transport": {
    "type": "streamable-http",
    "endpoint": "https://api.grep.ai/api/v2/mcp"
  },
  "auth": {
    "type": "oauth2",
    "resource_metadata_url": "https://api.grep.ai/.well-known/oauth-protected-resource/api/v2/mcp"
  }
}

Discovery

Where agents should look first.

The MCP Server Card is public, cacheable, and CORS-readable. OAuth metadata is separate so clients can discover authorization before sending a tool request.

MCP Server Card

Canonical public MCP discovery document for clients that probe the Cloudflare readiness path.

MCP JSON alias

Compatibility alias for clients that still probe the draft mcp.json location.

OAuth protected resource

RFC 9728 metadata for the MCP resource and accepted scopes.

Markdown twin

Crawler-friendly MCP setup notes for agents that prefer Markdown.

Tools

The MCP surface maps to public v2.

Research jobs

Create, continue, cancel, list, and inspect Grep research jobs through MCP tool calls.

Files and artifacts

List generated files, read text artifacts inline, and hand off large artifacts through signed URLs.

Attachments

Create, read, and delete research attachments for file-backed research workflows.

Custom experts

Create, configure, and maintain custom experts headlessly: skills, tools, context files, structured output, versions, and sharing.

Quota and billing

Check quota, usage, and billing transactions before launching expensive research.

Streamable HTTP

Use the public remote MCP endpoint over the current streamable HTTP transport.

OAuth resource metadata

Discover the protected resource, scopes, and authorization server before attempting connection.

Connect

Add Grep to your agent.

Same server, same OAuth flow — point any MCP-compatible client at https://api.grep.ai/api/v2/mcp.

Claude Code

Anthropic's terminal-based coding agent.

  1. Run the command below in any project.
  2. Run /mcp and choose Authenticate to finish OAuth in your browser.
bash
claude mcp add --transport http grep https://api.grep.ai/api/v2/mcp
Official docs

Cowork, Claude.ai & Desktop

Same connector flow across every Claude client.

  1. Open Customize → Connectors → + → Add custom connector.
  2. Paste the server URL below, click Add, then authenticate.
text
https://api.grep.ai/api/v2/mcp
Official docs

ChatGPT for Work

Business, Enterprise, and Edu workspaces (Developer Mode).

  1. In Settings → Advanced, turn on Developer Mode.
  2. Open Connectors, add a connector, and paste the server URL below.
text
https://api.grep.ai/api/v2/mcp
Official docs

Codex CLI

OpenAI's terminal coding agent.

  1. Run the command below, or add it directly to ~/.codex/config.toml.
bash
codex mcp add grep --url https://api.grep.ai/api/v2/mcp
Official docs

Experts

Build an expert headlessly.

Everything the Agent Builder UI does is available as MCP tools (and mirrored at /api/v2/experts), gated by the experts:read and experts:write scopes.

skills_list / skill_get / skill_create

Browse the skill catalog, read any SKILL.md, and author custom skills.

mcp_tools_list

List the MCP tools an expert can be granted.

expert_apply

Declarative Terraform-style sync: one manifest, one call — diffs desired vs current state (skills, config, context files) and performs the minimal delta. Idempotent; dry_run returns the plan.

expert_create / expert_get / expert_update / expert_delete / expert_list

Imperative lifecycle with the complete Builder config: output schema, SOP, input form, defaults, cost cap.

expert_build_start / expert_build_get

Alternative entry point: describe a domain and a builder agent designs the expert; poll to completion.

expert_context_file_upload / expert_context_files_list / expert_context_file_get / expert_context_file_delete

Attach reference documents — by source_url (server-side SSRF-guarded fetch, preferred), attachment_id, or inline base64. Archives are rejected (upload the members).

expert_versions_list / expert_version_get / expert_version_restore

Every change is snapshotted; restores are reversible.

expert_extract_config / expert_generate_workflow / expert_plan_preview

Preview config extraction, workflow authoring, and the research plan your SOP would produce — planning phase only, cents instead of full runs.

expert_share / expert_unshare / expert_shares_list / expert_set_visibility

Share with a user, an email domain, or a team.

key_create / key_list / key_revoke

Mint, inspect, and revoke your own parcha- API keys headlessly. A key's scopes are a subset of your OAuth token's; the secret is returned once, at creation.

1. Discover skills and tools

json
skills_list { "query": "financial analysis", "limit": 20 }
mcp_tools_list { "category": "screening" }

Filter server-side (query/category/server/limit) — the response's total tells you when to refine instead of paging. Tools flagged always_on ride with every run and need no grant. Author a bespoke skill if the catalog lacks one:

json
skill_create {
  "name": "credit-memo-writer",
  "description": "Writes a five-field credit memo from spread financials.",
  "content": "# Credit Memo Writer\n\nMethodology..."
}

2. Create the expert with structured output

json
expert_create {
  "name": "Merchant Credit Analyst",
  "system_prompt": "You are a credit analyst. Spread the financials...",
  "skill_names": ["credit-memo-writer", "financial-data-research"],
  "mcp_tool_names": ["parallel:web_search"],
  "output_schema": {
    "type": "object",
    "properties": { "icr": { "type": "integer", "minimum": 1, "maximum": 10 } },
    "required": ["icr"]
  },
  "input_form": [{ "label": "Company name", "type": "text", "required": true }],
  "max_cost_usd": 5.0
}

Supplying output_schema / output_sop makes structured output deterministic — no LLM extraction pass.

3. Attach context files (by URL, attachment, or inline)

json
expert_context_file_upload {
  "expert_id": "<id from step 2>",
  "source_url": "https://acme.example/chart-of-accounts.pdf"
}
expert_context_file_upload {
  "expert_id": "<id>",
  "attachment_id": "<research attachment id>"
}
expert_context_files_list { "expert_id": "<id>" }

Prefer source_url — the server fetches it (public http(s) only, SSRF-guarded, size-capped), so the bytes never transit your context window. attachment_id copies from a research attachment you own; content_base64/content_text remain for small inline files. Expand .zip archives client-side — the server rejects them.

4. Validate and iterate cheaply

json
expert_create { ..., "validate_only": true }
expert_update { "expert_id": "<id>", "system_prompt": "...v2...", "validate_only": true }
expert_plan_preview { "expert_id": "<id>", "question": "Spread FY2025 for Acme" }
expert_update { "expert_id": "<id>", "system_prompt": "...v2..." }

validate_only runs every check (skill/tool names, output_schema validity, template existence) without persisting; expert_plan_preview runs only the planning phase so SOP edits cost cents, not runs. The MCP schemas enumerate valid input_form types and output_type keys — no 422 archaeology. expert_update is a partial patch and every change lands in the version history.

Or: one manifest, one call

json
expert_apply {
  "manifest": {
    "name": "Merchant Credit Analyst",
    "system_prompt": "You are a credit analyst...",
    "skills": ["credit-memo-writer", "financial-data-research"],
    "custom_skills": [{ "name": "credit-memo-writer", "description": "...", "content": "# ..." }],
    "mcp_tool_names": ["parallel:web_search"],
    "output_schema": { "type": "object", "properties": { "icr": { "type": "integer" } } },
    "context_files": [
      { "name": "chart-of-accounts.pdf", "source_url": "https://acme.example/chart.pdf" },
      { "name": "icr-scale.md", "content": "1 to 10..." }
    ]
  },
  "dry_run": true
}

expert_apply replaces steps 1–4: it diffs the manifest against current state and performs the minimal create/update/upload/delete set — custom skills included. Re-applying an unchanged manifest is a no-op; drop dry_run to apply.

5. Run it

json
research_create {
  "question": "Spread FY2025 financials for Acme Corp",
  "expert_id": "<id>",
  "effort": "high"
}

The run stages the expert's context files into the sandbox and returns structured output matching the schema.

Discover

Fetch the Server Card.

bash
curl https://grep.ai/.well-known/mcp/server-card.json | jq
Authorize

Resolve OAuth metadata.

bash
curl https://grep.ai/.well-known/oauth-protected-resource/api/v2/mcp | jq
Connect

Point MCP clients at v2.

json
{
  "mcpServers": {
    "grep": {
      "url": "https://api.grep.ai/api/v2/mcp"
    }
  }
}

Give agents tool access without a browser.

Use REST and OpenAPI for direct integrations. Use MCP when an agent client wants tools, OAuth discovery, and a standard remote transport.

Server Cardv2 reference