The Integrations API connects projects to external services through four resources. REST, GraphQL, and MCP use the same resource names. The SDK covers integrations, connections, and integration tools. It has no project integration methods.
Integrations
The catalog is the same for every project. The integration catalog lists each integration with its authentication model, credential variables, and tools.
Experimental integrations need VERYFRONT_EXPERIMENTAL_INTEGRATIONS in the project environment. Set it to all or to a comma-separated list of integration names.
Project integrations
A project integration stores how one project uses one integration:
allowed_tools: The tools that agent runs andmockmode can use.nullallows every tool.config: Integration-specific settings that matchconfig_schema.execution_mode:realcalls the provider.mockruns the mock tools of the integration, for tests.scope:projectuses one shared connection.useruses the personal connection of each user.
PATCH /projects/{project_reference}/integrations/{name} changes only the fields you send. Send scope in the first update. Without it, the API stores project scope.
curl --fail-with-body -X PATCH \
"https://api.veryfront.com/projects/support-assistant/integrations/gmail" \
-H "Authorization: Bearer $VERYFRONT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"scope":"project","allowed_tools":["list_emails"]}'DELETE on the same path resets the settings to the defaults. It does not remove connections.
allowed_tools does not limit a direct run in real mode. There, the project permission of the credential decides: project.integrations.read, or project.integrations.connect for a tool that writes.
Connections
A connection authorizes one provider account. A project connection is shared. A user connection belongs to the person who authorized it. Project access does not grant access to another user's private connection.
The credential decides which connections a request sees:
- API key or service account: Shared project connections only.
- Signed-in user: Their own private connections and the shared project connections.
GET /projects/{project_reference}/connections lists the connections of one project. GET /connections lists the connections of the signed-in user across projects. It rejects an API key with 401.
Each connection has a connection_generation_id. It changes when the account behind the connection is replaced.
Attaching a tool to an agent does not supply a connection. Source-defined agent capabilities belong to the Agents API.
Authentication models
The provider decides how access is established. This authorization is separate from the Veryfront credentials in Authentication and access.
Managed and custom OAuth apps
A managed OAuth app lets users connect without a provider app of your own. Custom OAuth credentials take precedence, in this order: project integration credentials, project environment variables, then the managed app.
Use a custom app for consent branding, provider verification, or extra scopes. A failed connection can come from a callback URL, scope, or permission problem. The returned error identifies what to check.
Run an integration tool
- List the tools: Read the selected tool's input schema.
- Select a connection: Keep its
idandconnection_generation_id. - Check readiness: Stop when the tool is blocked.
- Run the tool: Send the arguments and the selected connection.
The examples send an API key, so they use a shared project connection. For a user scope integration, send the token of the user who owns the connection. With an API key, readiness reports a missing connection.
Write tools change external state. Start with a read-only tool.
List the tools
GET /integration-tools lists the tools the credential can run, with their input schemas. The integration tool routes take the project from the credential. If the credential is not bound to one project, send x-veryfront-project-slug.
curl --fail-with-body "https://api.veryfront.com/integration-tools?integration=gmail" \
-H "Authorization: Bearer $VERYFRONT_API_KEY" \
-H "x-veryfront-project-slug: support-assistant"Check readiness
Readiness checks stored metadata without contacting the provider. It reports eligible, blocked, or unknown. A blocked result is a response, not an error.
curl --fail-with-body -G \
"https://api.veryfront.com/projects/support-assistant/integrations/gmail/readiness" \
-H "Authorization: Bearer $VERYFRONT_API_KEY" \
--data-urlencode "tool_name=gmail__list_emails" \
--data-urlencode "connection_id=<CONNECTION_ID>"Read local_eligibility.state:
blocked: The tool cannot run.local_eligibility.blockerslists the reasons.eligible: A connected OAuth connection is selected.unknown: Stored metadata cannot decide. This is normal for project credentials and formockmode. Run the tool to get the result.
The readiness check refuses a run token or a service account with 403. With those credentials, skip it and run the tool.
Run the tool
POST /integration-tools/{tool_name}/run runs the tool synchronously. Put the provider arguments in arguments. expected_connection_generation_id rejects the run with 409 if the account was replaced.
curl --fail-with-body -X POST \
"https://api.veryfront.com/integration-tools/gmail__list_emails/run" \
-H "Authorization: Bearer $VERYFRONT_API_KEY" \
-H "x-veryfront-project-slug: support-assistant" \
-H "Content-Type: application/json" \
-d '{
"arguments": {"q": "in:inbox", "maxResults": 1},
"connection_id": "<CONNECTION_ID>",
"expected_connection_generation_id": "<CONNECTION_GENERATION_ID>"
}'The response is the tool result. A provider failure returns 200 with isError: true. Invalid arguments that fail a declared body input schema return 400 before the tool operation is sent. Authentication and scope checks may contact the provider first.
If a call is denied, check readiness when your credential supports it. Then check the credential's project permissions and the account's provider permissions. For an agent run or mock mode, also check allowed_tools.
SDK, GraphQL, and MCP
The SDK client runs the same flow:
import { createIntegrationClient } from "veryfront/integrations";
const client = await createIntegrationClient({
apiBaseUrl: "https://api.veryfront.com",
authToken: "<TOKEN>",
projectReference: "support-assistant",
});
const selection = {
connectionId: "<CONNECTION_ID>",
expectedConnectionGenerationId: "<CONNECTION_GENERATION_ID>",
};
const readiness = await client.readiness("gmail__list_emails", selection);
if (readiness.local_eligibility.state === "blocked") {
throw new Error(`Not ready: ${readiness.local_eligibility.blockers.join(", ")}`);
}
const outcome = await client.call(
"gmail__list_emails",
{ q: "in:inbox", maxResults: 1 },
selection,
);
console.log(outcome.status);GraphQL uses the integrationTools and integrationReadiness queries and the runIntegrationTool mutation. MCP uses veryfront__check_integration_readiness and the native tools/list and tools/call requests.
MCP lists and runs integration tools only on a project-bound request. Use a project-scoped API key or the /projects/{project_reference}/mcp endpoint. MCP does not read x-veryfront-project-slug. Pass the connection in _meta:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "gmail__list_emails",
"arguments": {"q": "in:inbox", "maxResults": 1},
"_meta": {
"connection_id": "<CONNECTION_ID>",
"expected_connection_generation_id": "<CONNECTION_GENERATION_ID>"
}
}
}Related resources
Connections also support external storage and messaging:
- External files: Browse and manage the files in a user's own OneDrive, SharePoint, or Google Drive. An import creates a project upload. It does not index the file for knowledge retrieval.
- Channels: Connect a messaging platform to a project agent.
Get started
Connect an integration explains project setup and verification. Set up Salesforce covers Salesforce-specific authorization.