Building plugins

One /v1 endpoint for every provider. Point your OpenAI client at a new base URL and key, bring your own provider keys, and pay 0% markup on tokens.

A plugin lets any organisation on the platform give models tools that you build: reading a Google Drive, searching a CRM, filing a ticket. An organisation installs your plugin from the marketplace, and from then on its requests can offer your tools to any model. The model decides when to call them, and we call your server and hand the answer back to the model.

A plugin is an MCP server that you host. We never run your code. We call your server over the network, the same way we call an organisation’s own MCP servers. If your plugin reaches another service, such as Google, it does that on your side with the access the organisation granted you. We hold only the organisation’s credential for your plugin, encrypted, and send it on each call.

Step 1: Build the MCP server

Your server must:

  • Speak the MCP Streamable HTTP transport, protocol version 2025-06-18: JSON-RPC by POST, answered as JSON or as an event stream.
  • Be reachable at a public https URL. Private and local addresses are refused, and redirects are not followed.
  • Answer initialize, tools/list and tools/call. We read up to 5 pages of tools.

Some limits shape what your tools should return:

  • Tool names may use letters, digits, _, . and -, up to 64 characters. A tool with any other name is not offered.
  • The model sees each tool as plugin__<slug>__<tool>, with hyphens in the slug turned into underscores. That name must fit in 64 characters, so keep the slug and tool names short.
  • Each tool’s description and inputSchema go to the model as they are. Write the description for the model: say when to use the tool and what it returns.
  • Results are text. We pass on the text content blocks. Other content types are replaced with a placeholder. If there is no text, we pass on structuredContent as JSON. A result with isError: true reaches the model as an error it can react to.
  • A response may be up to 1 MB. The model sees at most 100,000 characters of a result, and the rest is cut off.
  • A call has 120 seconds to answer.

Agent tools

A tool can be an agent. It can run many steps on your side, such as searching, reading and summarising, and answer once with the result. We call it like any other tool, so nothing extra is needed to build one. Finish within the 120 seconds, and return a short answer the model can use, not a log of every step.

Step 2: Choose how organisations sign in

Your server learns which organisation is calling only from the credential we send. Choose one of three:

  • none: no credential. Use it only for tools that serve public data.
  • api_key: you give each organisation a key, and they enter it when they install. We send it on every call in the header you name in auth_header (by default Authorization), exactly as they entered it. If your server expects Bearer, tell them to include it.
  • oauth2: the organisation signs in on your own authorization server, which is how they grant you access to their Google account, for example. We use the authorization code flow with PKCE (S256), and send Authorization: Bearer <access token> on every call.

For oauth2, register this redirect URI with your authorization server:

text
https://autonomousrelay.com/v1/auth/oauth/plugin/callback

Your token endpoint receives a form-encoded POST with client_id, and with client_secret if you gave us one. It must answer with JSON that includes access_token. If the answer includes expires_in and refresh_token, we refresh the token a minute before it expires. Without expires_in, we treat the token as one that does not expire. If a token expires and cannot be refreshed, the organisation is asked to connect again.

Step 3: Register the plugin

Register it from Plugins → Publish in the dashboard, or with a management key that has config:write:

curl
curl -X POST https://autonomousrelay.com/v1/plugins \
  -H "Authorization: Bearer $AUTONOMOUSRELAY_MANAGEMENT_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "slug": "drive-search",
    "name": "Drive Search",
    "summary": "Search and read the files in your Google Drive.",
    "publisher": "Example Labs",
    "mcp_url": "https://mcp.example.com/mcp",
    "auth": "oauth2",
    "oauth_authorize_url": "https://auth.example.com/authorize",
    "oauth_token_url": "https://auth.example.com/token",
    "oauth_client_id": "relay-client",
    "oauth_scopes": "drive.read",
    "privacy_url": "https://example.com/privacy",
    "categories": ["productivity", "data"]
  }'
  • slug: 2 to 40 lowercase letters, digits or hyphens. It is how requests name your plugin, and it cannot change.
  • name and publisher: up to 80 characters each. summary: up to 280. description: up to 4,000.
  • publisher is your own name or your organisation’s, and the marketplace shows it as “Built by” on your listing. Plugins we build are marked Official and show “Built by Autonomous Relay”; no one else may publish under that name. Changing publisher on a listed plugin sends it back to review.
  • homepage_url and privacy_url: public https URLs. Reviewers expect a privacy policy for any plugin that handles an organisation’s data.
  • categories: up to 5 of productivity, data, developer, search, communication, finance, marketing, sales, support and other.
  • oauth_client_secret: add it if your authorization server gave you one. It is encrypted when it is saved and never returned.

An organisation can register up to 20 plugins.

Step 4: Test it privately

A new plugin is private: only your own organisation can see it, install it and use it. That lets you test it end to end before anyone else can find it. Install it, then ask it for its tools:

curl
curl -X POST https://autonomousrelay.com/v1/plugins/drive-search/connect \
  -H "Authorization: Bearer $AUTONOMOUSRELAY_MANAGEMENT_KEY"

curl https://autonomousrelay.com/v1/plugins/drive-search/tools \
  -H "Authorization: Bearer $AUTONOMOUSRELAY_MANAGEMENT_KEY"

connect answers with an authorize_url to open in a browser. For an api_key plugin, install with POST /v1/plugins/{slug}/install and {"credential": "..."}. For a plugin with no sign-in, send an empty body.

Step 5: Submit it for review

When it works, submit it with POST /v1/plugins/{id}/submit, or with Submit for review in the dashboard. It is then pending. An Autonomous Relay reviewer either approves it, which lists it under Connections for every organisation to connect on its own, or rejects it with a note saying why. Fix what the note asks for and submit it again. A logo (PNG, JPEG, WebP or SVG, at most 64 KB) can be added or changed at any time, as the icon field, without a new review.

Changing publisher, mcp_url, auth, auth_header or any oauth_ setting of an approved plugin sends it back to review, because those settings decide what the plugin can reach. Your name, summary, description and categories can change without a new review. A plugin found misbehaving can be suspended, which stops every organisation’s calls to it at once.

How organisations use your plugin

Once an organisation installs your plugin, a request names it among its tools, with allowed_tools to offer only some of your tools. A request can name up to 5 plugins:

curl
curl -X POST https://autonomousrelay.com/v1/chat/completions \
  -H "Authorization: Bearer $AUTONOMOUSRELAY_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [{"role": "user", "content": "Summarise the Q3 plan in my Drive"}],
    "tools": [{"type": "autonomousrelay:plugin", "plugin": "drive-search"}]
  }'
  • 404: the organisation has not installed the plugin.
  • 403: the organisation installed it but turned it off.
  • 502: we could not list the plugin’s tools. The message says why, for example that an OAuth plugin is not connected yet.