Iris agent kit

Connect an AI agent to Iris, the AI receptionist by dotfun. This repo holds everything an agent client needs:

• the iris-api skill, which teaches an agent the Iris API and the daily operator routine,
• the Iris MCP server connection,
• the public OpenAPI document (openapi/openapi.json),
• a plugin marketplace for Claude Code and Claude Cowork, and one for Codex.

Site: https://dot-fun.github.io/iris-agent-kit/ serves llms.txt, llms-full.txt, openapi.json and the .well-known skill indexes.

Before you start

1. Get a key. In the Iris dashboard, open Organization > API keys. Create a key with the scopes the agent needs. Iris shows the key once.

2. Set the key. Export it as IRIS_API_KEY in the environment the agent runs in:

   export IRIS_API_KEY=iris_sk_...

3. Know the MCP status. The MCP server is https://api.iris.dotfun.co/api/v1/mcp. It is rolling out behind a feature flag. If your organization does not have it yet, the server answers 404, and the skill still works over plain REST with the same key.

Never commit the key or paste it into a chat.

Claude Code

Install:

/plugin marketplace add Dot-Fun/iris-agent-kit
/plugin install iris@iris

Or from a shell: claude plugin marketplace add Dot-Fun/iris-agent-kit, then claude plugin install iris@iris.

Auth: the plugin's .mcp.json sends Authorization: Bearer ${IRIS_API_KEY}. Start Claude Code from a shell where IRIS_API_KEY is set.

Update: the plugin has no version, so every commit to main is an update. Claude Code checks in the background. To update now, run /plugin marketplace update iris, then /plugin update iris@iris.

Claude Cowork and Claude Desktop

Install: in Cowork, or the Code tab of Claude Desktop, add the marketplace Dot-Fun/iris-agent-kit and install the iris plugin. The skill arrives with it.

Auth: the MCP connection in Cowork, Claude Desktop chat and claude.ai is a custom connector (Customize > Connectors, URL https://api.iris.dotfun.co/api/v1/mcp). These connectors cannot send an API key header. They need OAuth on the Iris server, which is not live yet. Organizations in Anthropic's request-headers beta can add Authorization: Bearer iris_sk_... under Request headers today.

Update: Cowork checks the marketplace for updates. Press Update on the marketplace page to pull now.

Codex CLI and Codex desktop

Install the plugin:

codex plugin marketplace add Dot-Fun/iris-agent-kit

Then open /plugins in Codex and install iris. To install only the skill, run $skill-installer install https://github.com/Dot-Fun/iris-agent-kit/tree/main/skills/iris-api inside Codex.

Auth: add the MCP server to ~/.codex/config.toml. The CLI, the desktop app and the IDE extension share this file.

[mcp_servers.iris]
url = "https://api.iris.dotfun.co/api/v1/mcp"
bearer_token_env_var = "IRIS_API_KEY"

Update: run codex plugin marketplace upgrade iris, then restart the desktop app. Codex caches the plugin by version, and every skill change here bumps it.

ChatGPT

Iris on ChatGPT waits for OAuth. ChatGPT connectors do not accept an API key, and the Iris server does not offer OAuth yet. This section changes when it does.

When OAuth ships: turn on Settings > Security and login > Developer mode, open chatgpt.com/plugins, press the plus button, and enter https://api.iris.dotfun.co/api/v1/mcp. ChatGPT reads the tool list live, so no update step exists.

Hermes Agent

Install the skill:

hermes skills install Dot-Fun/iris-agent-kit/skills/iris-api

Hermes asks for IRIS_API_KEY because the skill declares it.

Auth: add the MCP server to ~/.hermes/config.yaml:

mcp_servers:
  iris:
    url: "https://api.iris.dotfun.co/api/v1/mcp"
    headers:
      Authorization: "Bearer ${IRIS_API_KEY}"

Update: hermes skills check, then hermes skills update iris-api.

OpenClaw

Install the skill:

openclaw skills install skills-sh:Dot-Fun/iris-agent-kit/iris-api

The skill stays inactive until IRIS_API_KEY is set.

Auth: add the MCP server, then set the Authorization: Bearer ... header in the Settings config editor. Do not write the key into the config as a literal.

openclaw mcp add iris --url https://api.iris.dotfun.co/api/v1/mcp --transport streamable-http

Update: OpenClaw refreshes only ClawHub installs. Run the install command again to update.

npx skills

Install for one or more agents:

npx skills add Dot-Fun/iris-agent-kit
npx skills add Dot-Fun/iris-agent-kit --skill iris-api -g -a claude-code -a codex -a hermes -a openclaw -y

Auth: set IRIS_API_KEY, and add the MCP server in each client as its section above shows.

Update: npx skills update.

Gemini CLI

Install the skill:

gemini skills install https://github.com/Dot-Fun/iris-agent-kit.git --path skills/iris-api --consent

Auth: set IRIS_API_KEY. The skill calls the REST API with it.

Update: Gemini CLI has no update command. Run the install command again.

What is in this repo

Path	Used by
.claude-plugin/marketplace.json, .claude-plugin/plugin.json	Claude Code, Claude Cowork
.agents/plugins/marketplace.json, .codex-plugin/plugin.json	Codex
.mcp.json	Claude Code, Claude Cowork
skills/iris-api/	every client
openapi/openapi.json	code generators, the site
docs/llms.txt, docs/index.md	the site
scripts/build-site.mjs, .github/workflows/pages.yml	the site build

Maintaining

The Iris monorepo is the source of skills/iris-api/ and openapi/openapi.json. Its agent-kit-publish workflow copies them here on every push to its develop branch that changes the public API contract or the skill. Do not edit those two paths in this repo: the next publish overwrites them.

The rule: every change to an Iris /api/v1 route updates the skill and this kit in the same pull request. The monorepo enforces it. Its freshness check fails when the generated references/endpoints.md drifts from the OpenAPI document, or when the document has an operation the skill never names.

The Codex version rule: bump version in .codex-plugin/plugin.json in the same commit as any change under skills/. Codex caches plugins by version, so without a bump Codex users keep the old skill. The publish workflow does this for you (a patch bump). .claude-plugin/plugin.json has no version on purpose: Claude Code and Cowork treat every commit as an update.

The site rebuilds on every push to main. To build it locally, run node scripts/build-site.mjs and open _site/index.html. It needs Node 20 or newer and no packages.

License

MIT. See LICENSE.