Connections

What is a Connection?

A connection represents an end-user's authenticated link to a plugin. It stores encrypted credentials (OAuth tokens, API keys, etc.) scoped to a specific developer + user + plugin combination.

For MCP-enabled plugins, a connection can also store MCP-specific tokens (mcpAccessToken, mcpRefreshToken, mcpTokenExpiresAt) obtained via OAuth with PKCE. A single connection record can hold both REST and MCP credentials when using "both" tool source.

Connections Page

The dashboard connections page shows:

• Expandable user groups keyed by user ID
• Per-user connection cards with plugin name, auth type, label, and creation date
• Connection type badge — MCP, REST, or MCP + REST
• New Connection button to create test connections
• Get Tools button on each connection — fetches tools from the MCP server (if MCP tokens exist) or shows manual tools
• Disconnect actions can remove a connection and clear any live MCP client session for that user/plugin
• Sync to Plugin Toolkit button (admin only) — publishes discovered MCP tools to the plugin's tool cache

Creating a Test Connection

1. Click New Connection
2. Select a plugin and enter an end-user ID
3. The dialog generates a hosted connect URL
4. Copy the URL or open it to walk through the connect flow

Get Tools

The Get Tools button on each connection card:

• For MCP connections: connects to the MCP server using the user's access token and fetches all available tools in realtime
• For REST connections: returns the plugin's manually defined tools
• Displays tools in an expandable list with schema inspection

Sync to Plugin Toolkit

After successfully fetching tools via Get Tools, the Sync to Plugin Toolkit button appears for admin users. Clicking it:

1. Persists the discovered MCP tools into mcpToolCache
2. Makes them available to all users via getTools() as a fallback
3. Shows a success confirmation with the number of tools synced

Disconnecting a Connection

Connections can be removed through the dashboard API with:

DELETE /api/dashboard/connections

{
  "connectionId": "550e8400-e29b-41d4-a716-446655440002"
}

The connection must belong to the authenticated developer. When the connection includes MCP credentials, any cached live MCP client is closed before the database record is deleted.

Hosted Connect Pages

For OAuth-based, credential-based, or MCP connections, NIN provides hosted connect pages at /connect/[plugin]. These pages:

• Display the plugin name and available auth methods
• For MCP-enabled plugins: show a "Connect with [Service] MCP" button that initiates OAuth with PKCE
• For MCP plugins that allow end-user app credentials: show the callback URL plus optional client ID and client secret inputs
• For OAuth: redirect the user through the provider's authorization flow
• For API keys / bearer tokens: show a form where the user enters their credentials
• After submission, credentials are encrypted and stored as a connected account

Connection Flow (Programmatic)

From the SDK or API, there are three ways to create connections:

MCP OAuth (PKCE)

const { connectUrl } = await session.initiateConnection({
  plugin: "notion",
  connectionType: "mcp",
  redirectUrl: "https://your-app.com/callback",
});
// redirect user to connectUrl → Notion OAuth with PKCE

REST OAuth / Redirect

const { connectUrl } = await session.initiateConnection({
  plugin: "gmail",
  redirectUrl: "https://your-app.com/callback",
});
// redirect user to connectUrl

Direct Credentials

await session.createConnection({
  plugin: "openai",
  authMethod: "api_key",
  credentials: { api_key: "sk-..." },
});

To remove a saved connection:

await session.disconnectConnection({ plugin: "gmail" });

See the SDK docs, REST API, and MCP Integration for full details.