pickable.
Agent integration

Use Pickable
from your agent.

Public read tools can inspect Pickable and existing scans. Creating a scan is an explicit write action and needs an operator-configured key when called through MCP.

REST scan flow

  1. Call GET /api/config to receive a process-scoped CSRF token and current service mode.
  2. Post {"domain":"example.com"} or {"url":"https://example.com/product"} to /api/scans as application/json, with the token in X-CSRF-Token. The domain accepts a bare public domain or an HTTP(S) root URL. An operator-issued key can be used instead with Authorization: Bearer ….
  3. Poll GET /api/scans/{job_id} at a measured pace. The job can include a partial report while sources are still running.
  4. Read the redacted report or preview from the corresponding GET endpoints.

Scan history, reports, and previews are scoped to the caller’s direct network peer IP. This is not account authentication: callers behind the same proxy may share access. Raw provider responses are not exposed. Submit only public URLs without credentials.

MCP over Streamable HTTP

Use JSON-RPC 2.0 with HTTP POST /mcp. Include Content-Type: application/json and Accept: application/json, text/event-stream. Pickable returns single-message JSON responses and does not provide an event stream. Start with initialize, use the protocol version returned by the server, then send that value in MCP-Protocol-Version on subsequent requests.

Supported protocol versions are 2025-03-26 and 2025-06-18. Default tools are describe_pickable, list_scans, and get_scan_report (argument job_id). The optional start_website_scan tool is advertised only when the operator sets PICKABLE_MCP_SCAN_ENABLED=1 and configures PICKABLE_AGENT_API_KEY. Calls require a valid Authorization: Bearer … header and create a real asynchronous scan.

POST /mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"example-agent","version":"1.0.0"}}}

After initialize, include the negotiated value in MCP-Protocol-Version on each subsequent POST. The notifications/initialized notification is accepted with HTTP 202 and an empty body. GET /mcp returns 405; SSE subscriptions are unsupported. An enabled scan-start call with a missing or invalid bearer key returns 401. After authorization, domain, queue, and rate-limit failures are MCP tool errors in HTTP 200 responses; inspect isError and the error code in the text content. Successful calls using protocol version 2025-06-18 also include structured content.

Safe expectations: MCP read tools follow the same network peer scope as REST reads. Do not infer that Pickable has OAuth, A2A task processing, WebMCP, agent identity, or payment capabilities.

Discovery

Read as Markdown: agent-scan.md. Inspect tools/list at runtime for actual advertised tools.