Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Build a custom connector with your agent

An agent can turn a supported API definition into a private Stackyapper app. Your team discovers its permitted tools through the same MCP connection used for other apps.
Workspace owners and admins can create custom connectors. New connectors are Beta. Saving a definition does not connect an account or give anyone access.

Build from your API documentation

Give your agent the official API documentation, the system to connect, and a small task to support. For example:
Use the mcp-app-authoring skill to build a private connector for our inventory API from this documentation. Start with the documented current-account check and one item lookup. Validate the definition and explain any unsupported operations before creating it. I will connect the account in Apps.
The built-in mcp-app-authoring skill includes a sample OpenAPI definition. The agent must replace its example server and operations with documented ones; the sample is not a working connection to a real system.
  1. Define the tools. The agent writes an OpenAPI 3.0 or 3.1 JSON definition with the real HTTPS API address, authentication method, and input and response fields. Start with a few useful reads. Connection setup needs a supported read-only account or current-state check with no required inputs; if the API has none, the agent should report that limit.
  2. Validate. The agent uses stackyapper_validate_connector to inspect the definition. Review supported and skipped operations and any setup blockers. Validation does not call your system or save an app.
  3. Create. After your confirmation, the agent uses stackyapper_create_connector with the exact validated definition. It then uses stackyapper_get_connector to inspect the saved app and return the Apps setup link.
Keep API keys, tokens, client secrets, authorization values, and customer records out of the definition and agent conversation. Declare how authentication works; enter the actual credentials only in Stackyapper's connection setup.

Supported definitions and limits

Authoring accepts OpenAPI 3.0 or 3.1 JSON with public HTTPS API addresses. Supported account setup includes compatible bearer, Basic, header API-key and OAuth definitions. OAuth support depends on the provider and the connection options shown in Apps; an OpenAPI OAuth declaration alone is not enough. Query-string API keys and arbitrary authentication handlers are not supported by automatic setup.
Keep each definition below 5 MiB and 900 operations. The imported app and its compiled tools must each fit the storage limit; a large or deeply nested definition may need splitting even with fewer operations. Validation explains unsupported operations. Start with a small read that returns useful fields, and provide supported pagination for collections.

Use the portal instead

If your client cannot use the authoring tools, open Apps → Build with your agent. Copy the instructions for your agent, paste its OpenAPI JSON into Connector definition (OpenAPI JSON), and select Inspect schema. Review the result, then select Create private app. Invalid definitions and failed saves stay available to correct and retry.

Connect the account and grant access

Open the private app in Apps:
  1. Use Connections to configure the account. Supply any required OAuth developer registration there.
  2. Confirm the displayed read-only credential check and activate the supported tools when the connection is ready.
  3. Use Tools & access to choose the people or groups and tools to allow.
  4. Ask an authorized agent for one small read and check the result in Audit.
Connecting and granting access are separate steps. Each caller needs current permission, and a shared view does not lend its author's account to other users. After an uncertain creation response, inspect Apps before creating another copy. Use the app's Definition controls or ask your agent to preview an update.

Manage private app permissions with your agent

Workspace owners and admins can ask their agent to review and change a private app’s tool access for a workspace member or group. The agent uses stackyapper_inspect_permissions with resource: private_app_access to read the current selection, then proposes the complete set of tools to keep or remove. After your approval, it saves the selection with stackyapper_manage_permissions and action: private_app_access and reads it back.
Ask for access based on the team’s tasks. A permission update applies to one member or group at a time; other assignments can still provide access. Existing blocks and sensitive-tool approval requirements still apply. If permissions change while the agent is preparing an edit, it must read them again before saving.

Set up a connector for a managed customer

An owner or admin of an eligible managing workspace can open a managed customer from Customers and configure a private app there. Import the definition or MCP endpoint in the customer's Apps, connect that customer's account, and check the connection before granting access. Use a separate connection and permissions for each customer.
Choose customer groups when saving initial permissions. You can then edit access for individual customer members in Tools & access. If you only administer the customer through your managing workspace, Just me and Enable for me are unavailable. Create a customer group in Team if none exists yet.
Managing a customer does not make your account a customer member or authorize your AI client to run its tools. Customer users connect their own AI clients and need current tool permissions. Suspended customers and revoked management access cannot be configured through the managing workspace.

Update a connector with your agent

For an uploaded OpenAPI connector, ask your agent to read the current connector revision, inspect the saved contract, and validate the revised OpenAPI definition. The saved contract describes the imported operations; it is not a copy of your original OpenAPI file. Keep that original file for future edits.
For an incomplete schema, ask the agent to inspect saved operation diagnostics, including skipped calls. With stackyapper_get_connector, it supplies operation_cursor=0 and the current expected_revision_sha256, then follows operation_page.next_cursor at that revision. Each call includes its method, path, compatibility reason, repair guidance, and a pointer into the saved normalized contract. The agent should use provider documentation to supply missing fields or supported pagination; a small sample does not prove a list is bounded.
Code Mode can help inspect these authorized reads and transform schema JSON in small pages. Saving a repair still uses the normal confirmed update tool outside Code Mode, followed by connection checks and activation. Code Mode does not add arbitrary provider HTTP access or grant workspace permissions.
The agent supplies the connector ID and current revision to stackyapper_validate_connector, follows every page of changes, and explains which tools will change. After your confirmation, it supplies the exact preview to stackyapper_update_connector. Another administrator's change makes the preview stale; the agent must read and preview again.
Applying saves the definition and pauses calls. Return to Apps to review the updated tools, reconnect or check credentials, activate, and confirm access. The update does not call your API or grant access to new tools. Connectors imported from a URL, registry, or remote MCP server use Definition in Apps.
If an update response is interrupted, inspect the current revision before retrying. If the new revision is already saved, finish its setup instead of applying it again.

Check what is still missing

Ask your agent to inspect the saved connector with stackyapper_get_connector. It reports whether the current connection, credential check, activation, or your assigned tool access still needs attention, and suggests the next setup step. If the check is unavailable, use Apps to confirm the state before running tools. Disabled connectors remain unavailable; inspection does not turn them back on.
Assigned access is one part of permission. Your AI client's policy and the checks made when each tool runs still apply. A ready connection does not grant everyone access or establish that a particular client can run every tool.

Connect an existing MCP server

For a server you already host, use Apps → Import private app, choose MCP resource, and enter its MCP resource URL. Select a supported connection method and follow the review, connection, and access steps. Inspection reads the tool catalog without calling its tools.
Enter the full public HTTPS endpoint, including its path. Direct import uses Streamable HTTP. A server available only through a local command (stdio), a private network, or the older two-endpoint HTTP/SSE transport needs a compatible public HTTPS bridge that you host.
The OpenAPI authoring tools do not deploy an MCP server. You remain responsible for hosting your API or remote MCP server.

Local servers and other authentication methods

A customer-hosted bridge can expose a local command, private-network server, or legacy SSE server through an HTTPS MCP endpoint. The repository includes a preview bridge with bearer admission and installation-local provider credentials. See the bridge setup guide. It supports anonymous upstreams, bearer, Basic, custom headers, query keys and a documented HMAC adapter contract. These are bridge profiles; direct private-app connection options remain the methods shown in Apps. Each viewer still needs permission and an appropriate connection. The bridge does not delegate the operator's personal sign-in to other users.

Request formats

A reviewed OpenAPI call can use scalar parameters, bounded query arrays with repeated, comma, space or pipe separators, and closed scalar deepObject queries. JSON, URL-encoded forms and closed scalar multipart forms are supported. A multipart field declared type: string, format: binary takes base64 data; files and complete requests must fit the request limits. This does not add arbitrary file URLs or background uploads. Unsupported serialization or custom field encodings need a revised definition or a separate adapter.
OpenAPI 3.1 and MCP schemas can use const for a fixed string, number, integer or boolean when the field declares its type. Requests must use that value, and returned fields must match it. Nullable scalar fields can also specify const: null. Object and array constants, untyped constants and conflicting const/enum values remain unsupported.

Start from cURL or Postman

Run the repository's local converter before sharing a draft with your agent:
npm run app:convert -- curl request.txt https://api.example.com/v1/ connector.json
npm run app:convert -- postman collection.json https://api.example.com/v1/ connector.json
The converter sends no requests and executes no shell commands or collection scripts. It discards authentication settings, query/header values, body values, response samples and descriptions. It retains the supplied API base, URL paths and field names: inspect those for embedded secrets or customer identifiers before sharing the output. Scripts, unresolved variables, file references and unsupported cURL options are rejected.
The result is a draft. Add the documented response fields, array limits, pagination and correct authentication before normal validation. A request sample cannot prove a response schema or collection limit. The converter never creates or connects an app itself.

Add an interactive app

Use your agent to build an interactive MCP app over permitted private reads. On an available read in Tools & access, expand Build an artifact with this read. Give your agent the app and tool selection and ask it to use stackyapper_prepare_artifact_binding. It lists your permitted reads, returns a selected input schema and prepares an interactive starter. Follow its pages when there are more reads to choose from.
Inspect the arguments and output schema, adapt the starter, then validate, save and open the artifact using the existing artifact tools. The starter includes loading, unavailable, empty and stale-result guidance. Each viewer uses their own current access; creating a view does not call the provider or grant access. Imported writes and unattended refresh remain unavailable through this flow. Artifact hosting requires an approved Business workspace. Starter inputs are temporary. Persistent customer-app state is a separate private pilot.
Importing an MCP server's tools does not import its original interactive HTML. An upstream MCP Apps resource needs separate source and security review and a compatible host. Use an authored artifact over the imported reads when that interface is unavailable.