Manage applications through REST and MCP

Use REST when a trusted service deterministically manages application records. Use MCP when an authorized AI client should choose among the released list, create, or update actions with human review.

Application management is security-sensitive. Verify the caller's application/admin authority and inspect runtime schemas before writing.

Released REST directory

The public REST reference includes:

GET  /api/applications
POST /api/applications
GET  /api/applications/{appId}
PUT  /api/applications/{appId}

Use GET https://usable.dev/api/docs from the target environment for exact fields, authentication, and response shapes. Do not translate MCP arguments directly into REST payloads.

REST workflow

A safe application registration sequence is:

inspect OpenAPI → list existing apps → prepare draft metadata → create → store app ID → fetch → test → update deliberately

Before retrying a create request after a timeout, list applications and check whether the record already exists. Name alone may not be globally unique, so preserve returned IDs.

Use placeholders in examples and logs:

{
  "name": "Example integration",
  "icon": "https://app.example.com/icon.png",
  "description": "Connects approved workspace data to Example.",
  "developer": {
    "name": "Example Developer",
    "contactEmail": "support@example.com"
  },
  "category": ["productivity"],
  "oauthConfig": {
    "redirectUris": ["https://app.example.com/oauth/callback"],
    "applicationType": "web",
    "grantTypes": ["authorization_code", "refresh_token"]
  }
}

This is an intent example, not an exhaustive REST schema. Consult /api/docs for required token/access settings.

MCP manage-application

The released MCP tool supports actions:

• list — applications the caller owns or administers;
• create — register an application with OAuth and token configuration;
• update — modify supported metadata or lifecycle status.

Discover the deployed input schema with MCP tools/list. The current schema includes public metadata, developer, category/tags, OAuth configuration, token policy, consent permissions, access policy, admins, and supported update fields.

List example:

{
  "action": "list",
  "outputFormat": "json"
}

For create, pass only reviewed placeholder-derived values at runtime. Never send generated secrets back to the model or save them in a fragment.

Update requires appId and a changes object. The current tool update surface supports fields such as name, icon, descriptions, app URL, status, category, and tags. Use dashboard or the documented REST route for configuration not accepted by the tool.

Agent safety

When an AI client manages applications:

1. List existing apps first.
2. Require an explicit target application ID for updates.
3. Draft metadata for human review.
4. Keep new apps in draft.
5. Require confirmation before beta, active, deprecated, or archived transitions.
6. Do not allow the model to invent redirects, administrators, permissions, or contacts.
7. Never expose credentials to the model.
8. Fetch the result and verify it.

The application tool's current permission declaration and effective app-admin checks must both pass. A visible tool is not proof that a specific action is authorized.

Idempotency and verification

• Preserve application IDs in service state.
• Check for prior completion before retrying creation.
• Update only changed fields.
• Fetch after create/update.
• Test the selected grant in a safe environment.
• Verify marketplace visibility matches status and access policy.
• Record non-sensitive change ownership and time.

Do not use repeated create calls as an update mechanism.

Hosted Zone behavior

Application management remains a Cloud-owned operation. For MCP clients connected through a Leaf endpoint, manage-application is proxied to Usable Cloud in the released Hosted Zone routing model.

Do not include private Leaf workspace content in application metadata or Cloud management requests. Hosted Zone placement does not change application-admin requirements.

Troubleshooting

400 or schema error

Check URL/email formats, required category and developer fields, application type, grants, redirect URIs, token configuration, access policy, and unsupported extra fields.

401 or 403

Confirm authentication, tool/API permission, and ownership or app-admin authority. Workspace ownership alone may be insufficient.

MCP tool is missing

Call tools/list against the exact endpoint with the intended credential. Client compatibility modes or permissions can affect visible tools.

Update cannot change OAuth settings

The MCP update action intentionally exposes a narrower changes object. Use the supported application dashboard or deployed REST schema.

Device Code connection fails

Confirm device_code is configured, the client handles expiry and polling intervals, the user approved the correct app, and the environment includes the released Device Code support.

App is not visible in Marketplace

Confirm status and access policy. Draft apps are intentionally not public; beta or active visibility should follow review, not troubleshooting convenience.

Connection succeeds but workspace action fails

Application authorization and workspace permission are separate. Check the connected user's workspace access and the requested scope.

Related pages

• API resource directory and OpenAPI
• MCP tools and permissions
• Create and manage an application
• Configure permissions, access, and token security