Falconer agent integrations

Falconer Agent Integrations packages Falconer for AI agent clients that support hosted HTTP MCP servers.

This repository is pre-release. Static manifest validation has passed, but live hosted HTTP OAuth smoke tests in Cursor, Claude Code, and Codex are still pending. Do not submit or resubmit marketplace listings from this repository until those client smoke tests pass.

This repository intentionally does not document local stdio MCP installs. Clients are added only after hosted HTTP OAuth is verified end to end.

Supported clients

Client	Status	Install surface
Cursor	Pending live validation	Cursor plugin package and hosted MCP configuration
Claude Code	Pending live validation	Claude Code plugin marketplace package
Codex	Pending live validation	Codex plugin marketplace package

What this integration provides

• Hosted HTTP MCP connection to https://falconer.com/api/mcp.
• Agent guidance for reading, writing, and updating Falconer documents safely.
• Current formatting and component guidance loaded from the connected Falconer MCP server.
• Marketplace/plugin metadata for Cursor, Claude Code, and Codex.

Cursor

Falconer is packaged as a Cursor plugin under plugins/falconer. The package includes:

• .cursor-plugin/plugin.json
• mcp.json
• skills/falconer-knowledge/SKILL.md

The MCP server configuration is:

{
  "mcpServers": {
    "falconer": {
      "url": "https://falconer.com/api/mcp"
    }
  }
}

Live Cursor OAuth, install, search, and read smoke tests are still required before marketplace submission.

Claude Code

Add this repository as a Claude Code marketplace, then install the falconer plugin from that marketplace.

The Claude package uses hosted HTTP MCP through:

{
  "mcpServers": {
    "falconer": {
      "type": "http",
      "url": "https://falconer.com/api/mcp"
    }
  }
}

Live Claude Code OAuth, install, search, and read smoke tests are still required before treating this package as supported.

Codex

Add this repository as a Codex plugin marketplace and install the falconer plugin. The plugin includes a bundled hosted HTTP MCP configuration and the shared Falconer skill.

Live Codex OAuth, install, search, and read smoke tests are still required before treating this package as supported.

OpenAI directory package

The maintained OpenAI listing and review metadata are in plugins/falconer/.openai-plugin/plugin.json. The OpenAI connection and packaged README come from mcp.openai.json and README.openai.md. The .openai-plugin directory is this repository's build-input convention; the build exports its manifest as standard root plugin.json. Shared skills, assets, license and trademark files are included from their maintained source locations.

From the repository root, build the uploadable ZIP in dist:

python3 scripts/build-openai-plugin.py

To also write versioned release snapshots under submissions/openai/plugins:

python3 scripts/build-openai-plugin.py --archive

The build includes only explicitly listed public input files; unlisted local files under assets or skills are excluded. Review new public assets or skills before adding them to the build mapping. The build uses fixed ZIP metadata for reproducibility and never reads an earlier archive as build input. It refuses to replace an archived version with different bytes; update the source manifest's version before archiving a changed package. Release folders contain generated snapshots, and future metadata changes belong in the maintained source manifest. Keep reviewer credentials outside the package, and run the review cases with the supplied account before final submission. Run the focused package-input regression with python3 -m unittest discover -s tests.

Knowledge and document authoring

The shared skill loads Falconer's knowledge catalog at runtime through falconer_knowledge. Call the tool with {} to list topics, then with {"topic":"document-format"} before drafting or editing document content. Load document-components, html-components, or diagrams before using those features. MCP resources expose the same catalog under falconer://knowledge/ for clients that can attach resources as context.

Formatting guidance is maintained by the Falconer server and is not bundled in this plugin. If the server cannot return a required guide, report the failure before attempting content that depends on it.

The generic catalog is also available without workspace access through the knowledge API and the document-format topic. These endpoints contain product guidance only; hosted MCP connections still require authentication.

Compatibility policy

New clients are added only when all of the following are true:

• The client can connect directly to https://falconer.com/api/mcp.
• Hosted HTTP OAuth works end to end.
• search and read succeed in a smoke test.
• falconer_knowledge can list topics and load the document-format guide.
• Tool permission behavior is verified for write and admin tools.
• The working path does not require local stdio.

Security

Do not commit credentials, OAuth tokens, local MCP configuration, customer content, organization IDs, document IDs, screenshots containing private data, or local environment files to this repository. Keep local plans and audit evidence in the ignored tasks/ directory.

Report security issues through the process in SECURITY.md.

License

Code and documentation are licensed under Apache-2.0. Falconer names, logos, and marks are not licensed under Apache-2.0; see TRADEMARKS.md.