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	Custom tool definitions (ToolFactory) 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.

Tool Library

The Tools section (/developer/tools) serves two purposes:

1. Standard Tool Library — a read-only catalog of all engine-native tools organized by category (Filesystem, Shell, Git, Web, Communication, Knowledge, and more). These tools are informational — they cannot be modified or added, but you can reference them by name in Skill manifests.
2. Custom Tools — ToolFactory tools you create with Python source code. These are full tool definitions with parameters, source code, and credential requirements that you build and maintain.

See Building an App and Building a Skill for the manifest format and step-by-step guides.

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)