Developer Guide

Build integrations that connect ORQO to any external service. This guide covers the architecture, contracts, and decisions you need to make — whether you're building an App, a Skill, or both.

Integration Types at a Glance

ORQO has two integration primitives: Apps and Skills. They serve different roles and can work independently or together.

	App	Skill
What it is	An external HTTP service (adapter) that ORQO calls	A bundle of tools, credentials, and knowledge assigned to agents
Lives where	Runs as a service you host with its own URL	Configuration stored in ORQO
Provides	OAuth, webhooks, channel routing, MCP tools	Tool access, credential wiring, agent knowledge
Examples	Slack, Receive SendGrid Emails, Gmail	Send Mail, Web Research, Bannerbear
When you need it	External API that needs auth management, webhook handling, or protocol translation	Agents need tools — whether built-in, from MCP servers, or from an App

Common Patterns

Pattern	When to Use	Example
App + auto-created Skill	External service with OAuth and MCP tools	Google Drive, Gmail, Slack
Skill only	Tools that use built-in engine capabilities or simple API keys	Send Mail, Web Research, Code Review
App only (receive)	Inbound channel (webhooks) without agent tools	Receive SendGrid Emails
App + Skill (send/receive)	Full channel communication with agent tools	Slack, Telegram, WhatsApp
MCP Server (no App, no Skill)	Existing MCP-compatible tool server you want to connect directly	Brave Search, a custom database MCP

Decision: Do You Need an App?

Ask these questions:

1. Does it need OAuth? → You need an App. Apps manage the OAuth flow, token storage, and automatic refresh.
2. Does it receive webhooks? → You need an App. Apps provide webhook endpoints and signature verification.
3. Does it send/receive messages through channels? → You need an App with send/receive capabilities.
4. Does it just expose tools behind a simple API key? → A Skill is probably enough. Wire the API key as a credential, add the tool names, done.
5. Is it an existing MCP server? → Connect it directly in Settings > MCP Servers. No App or Skill needed (though a Skill makes it easier to assign to agents).

The MCP Question

Not every integration needs an MCP server. MCP (Model Context Protocol) is the standard for tool servers — but ORQO's engine already provides a large set of built-in tools (web search, file operations, shell, git, HTTP requests). If the tools you need already exist, you only need a Skill to bundle and assign them.

You need a custom MCP server (via an App adapter) when:

• The external API has no built-in tool equivalent
• You need platform-specific protocol translation (e.g., Google Drive's export API, Gmail's RFC 2822 messages)
• Tools need stateful context (e.g., maintaining a database connection)

You don't need a custom MCP server when:

• Built-in tools cover the use case (http_request for simple REST APIs, web_search + web_scrape for web research)
• An existing MCP server already provides the tools (connect it in Settings)
• The skill only needs knowledge and credential wiring, not new tools

Becoming a Developer

There are two paths to access the Developer Portal:

Path	Who	How
Freelancer self-signup	Independent developers without an existing ORQO account	Sign in at the Developer Portal login page with Google or GitHub OAuth. A developer account is created automatically.
Team member	Existing ORQO users within an organization	An organization owner enables the developer flag on your account. You then access the portal at /developer.

Both paths give you full access to create, manage, and publish integrations.

The Developer Portal

All integrations are registered through the Developer Portal, which is organized into four sections:

Section	URL	What it manages
Apps	/developer/apps	Adapter-based integrations with channels, OAuth, webhooks, and triggers
Skills	/developer/skills	Engine-facing packages bundling tools, knowledge, MCP servers, and credentials
Tools	/developer/tools	Your custom tool definitions (My Tools) and the standard Tool Library catalog
MCP Servers	/developer/mcp	MCP server connections for tool discovery

Registration Workflow

1. Build your adapter (Apps) or identify the tools you need (Skills)
2. Create a manifest.json that describes your integration
3. Register in the appropriate Developer Portal section by entering your manifest URL
4. Review your integration on its detail page — inspect parsed manifest sections, verify adapter connectivity, and check discovered tools
5. Submit for review → your integration is published to the marketplace

Detail Pages and Verification

After creating a listing, the Developer Portal shows a detail page with all parsed manifest sections: overview, credentials, MCP auth, skill definition, OAuth config, and setup instructions. The raw manifest JSON is available in a collapsible section at the bottom.

• App detail pages are at /developer/apps/:slug
• Skill detail pages are at /developer/skills/:slug

For App listings with an adapter URL, a Verify button probes the adapter's /health endpoint and runs MCP tools/list discovery inline. This lets you confirm your adapter is reachable and tools are discoverable before submitting for review.

My Tools and the Tool Library

The Tools section (/developer/tools) has two tabs, one for each kind of tool:

1. My Tools — the custom ToolFactory tools you built (or had the Tool Builder build for you). These are full tool definitions with editable Python source code, parameters, a category, and credential requirements that you build and maintain. You see the tools you've built for this workspace — your own authored tools, scoped to the org you're working in, not other developers' tools and not the whole platform library.
2. Tool Library — a read-only catalog of all engine-native standard tools (Python classes that live in the platform engine, resolved by name), organized by category (Filesystem, Shell, Git, Web, Communication, Knowledge, and more). These tools are informational — you can't modify or add them, but you can reference them by name in Skill manifests.

Each custom tool you create carries:

• a Category — a simple grouping you choose to organize your tools (cosmetic, used for filtering the list).
• a Requires Runtime toggle — turn it on when a tool needs to run on a remote runtime (heavy dependencies, or restricted operations like shell and file access). The security scanner turns this on and locks it automatically for tools that use shell commands or file operations; when locked, it's shown as locked and can't be turned off without re-writing the code.

On both tabs, each tool card displays its properties as pills — category, Requires Runtime, parameter count, and required credentials — and the list filters live as you type, with category filter pills.

See Building an App and Building a Skill for the manifest format and step-by-step guides, and the Tools reference for how the layers fit together.

What's in This Section

Page	What You'll Learn
Integration Hierarchy	How Tools, Credentials, Skills, and Apps fit together — with real examples
Hosting & Runtime	Where your adapter actually runs — ORQO-hosted vs Bridge vs self-hosted, the trust boundary, and how to choose
Building an App	Adapter development, manifest format, MCP tools, OAuth config, Developer Portal registration
Building a Skill	Manifest format, tool selection, knowledge writing, credential requirements
Adapter Contract Reference	Complete HTTP endpoint spec for App adapters
Credential Lifecycle & MCP Auth	How credentials flow to the engine, OAuth refresh, tool discovery
Shared Credentials	How multiple integrations share a single credential (e.g., Google OAuth)