AI Agent Skill¶

The IPTO CLI ships with a built-in AI agent skill that exposes marketplace operations as tools any MCP-compatible AI assistant can invoke. Once installed, agents can search datasets, upload files, manage API keys, and review analytics using natural language --- no manual CLI invocations required.

What Is the IPTO Skill?¶

The skill is an MCP (Model Context Protocol) compatible tool definition that bridges AI assistants and the IPTO API. When an agent has the skill installed, it can translate high-level user requests ("find all 2024 earnings reports") into structured API calls, execute them, and return the results --- all within the conversation.

Installation¶

Standard Install¶

ipto skill install

This registers the IPTO skill with your local AI agent environment.

Claude Code¶

For Claude Code specifically, use the dedicated flag:

ipto skill install --claude-code

OpenAI-Compatible Agents¶

For agents that follow the OpenAI function-calling convention:

ipto skill install --openai

Info

The install command writes the tool definitions to the location each agent runtime expects. You only need to run it once per machine (or after a CLI update).

What the Skill Exposes¶

The following tools become available to any connected agent:

Tool	Description
`ipto_search`	Search across datasets with natural language or structured queries.
`ipto_upload`	Upload files to a dataset.
`ipto_datasets_list`	List available datasets.
`ipto_datasets_create`	Create a new dataset.
`ipto_objects_list`	List objects in a dataset.
`ipto_objects_download`	Download an object.
`ipto_keys_create`	Create a scoped API key.
`ipto_analytics`	View provider dashboard and dataset analytics.
`ipto_spend`	View buyer spend summary.

Configuration for AI Agents¶

The skill reads authentication credentials from the same sources as the CLI: ~/.ipto/config.toml or the IPTO_API_KEY environment variable.

# Set up API key for agent use
ipto login --api-key ipto_abc_your_key_here

# Install the skill
ipto skill install

Use least-privilege API keys

Create a dedicated API key with only the scopes your agent needs. For example, a search-only agent should have an API key scoped to search and datasets.read --- nothing more.

ipto keys create --name "agent-search-only" --scopes search,datasets.read

MCP Server Mode¶

For advanced integrations, the CLI can run as a persistent MCP server that communicates over JSON-RPC on stdin/stdout:

ipto mcp serve

This starts a long-running process that any MCP-compatible client can connect to. The server exposes the same tool set listed above and handles authentication, request routing, and response formatting.

$ ipto mcp serve
MCP server listening on stdio (JSON-RPC)...

Tip

MCP server mode is ideal for custom agent frameworks or orchestration layers that manage their own tool lifecycle. For standard setups, ipto skill install is simpler.

Example Agent Interactions¶

Below are examples of natural-language requests and the tools the agent invokes behind the scenes.

Search for data¶

User: "Search IPTO for quarterly earnings reports from 2024."

The agent calls ipto_search with query "quarterly earnings reports 2024" and returns matching objects with relevance scores.

Upload files¶

User: "Upload all PDFs in ./reports to the financial-data dataset."

The agent calls ipto_upload with the dataset ID and file path, handling the presigned upload flow automatically.

Check spending¶

User: "How much have we spent on searches this month?"

The agent calls ipto_spend and summarizes the current billing period's search costs, broken down by dataset.

Security¶

The skill inherits the permissions of the configured API key. It cannot perform actions outside the key's granted scopes.

Principle of least privilege

Always create a dedicated API key for agent use. Avoid sharing your personal or admin key with automated agents.

# Create a restricted key for the agent
ipto keys create \
  --name "claude-agent" \
  --scopes search,datasets.read,objects.read \
  --access-mode allow_list

# Grant access only to specific datasets
ipto keys grant <key_id> --dataset d_01JQ3N...

Uninstall¶

Remove the skill registration from your agent environment:

ipto skill uninstall

This removes the tool definitions. It does not delete your API keys or configuration.

FAQ¶

Which AI agents support this?

Any agent that implements the Model Context Protocol (MCP) can use the IPTO skill. This includes:

Claude Code (Anthropic)
Claude Desktop (Anthropic)
GPT with function calling (OpenAI) via the --openai install flag
Custom agents built on MCP-compatible frameworks

If your agent supports a different tool protocol, use ipto mcp serve as a bridge.

Does it work offline?

No. The skill calls the IPTO API, which requires network access. If the API is unreachable, the agent will receive an error response it can relay to the user.

How do I restrict what the agent can do?

Scope is controlled entirely by the API key:

Create a key with only the scopes you want: ipto keys create --scopes search,datasets.read.
Optionally use allow_list access mode and grant access to specific datasets only.
The agent cannot perform any action outside those scopes, even if the user asks.

Can multiple agents share an API key?

Technically yes, but it is not recommended. Each agent should have its own key so you can:

Audit usage per agent.
Revoke a single agent's access without affecting others.
Apply different scope restrictions per agent.

How do I update the skill after a CLI upgrade?

Re-run the install command after updating the CLI:

npm update -g @ipto/cli
ipto skill install

The install command overwrites the previous tool definitions with the latest version.