Credentials

Securely store and retrieve authentication credentials for MCP servers.

Step 1: Add a credential

Make sure your Visual Builder is running (if you haven't set it up yet, see Quick Start). Navigate to the Credentials tab in the left sidebar and click "New credential".

Select "Bearer Authentication" and click "Create Credential". You'll then be prompted to enter your API key for the MCP server.

Step 2: Retrieve the credential reference id from the URLs

Once you've created a credential, you can retrieve the credential reference id from the URL. The credential reference id is the last part of the URL after credentials/ on the page of the credential you just created.

Step 3: Reference the credential when creating an MCP tool

There are two ways to reference credentials in your MCP tools:

Option 1: Reference by Credential ID (Recommended)

When you create a credential through the UI, you get a credential reference ID that you can use directly:

import { mcpTool, MCPTransportType } from '@inkeep/agents-sdk';

// Use the credential reference ID from the UI
const inkeepAnalyticsTool = mcpTool({
  id: 'inkeep-analytics',
  name: 'inkeep_analytics',
  description: 'Get the latest stats from the Inkeep Analytics dashboard',
  serverUrl: 'https://analytics.inkeep.com/mcp',
  credentialReferenceId: 'your-credential-id-from-ui', // Credential ID from Step 2
  transport: {
    type: MCPTransportType.streamableHttp,
  },
});

Option 2: Define Environment-Based Credentials

For development workflows, you can define credentials that reference environment variables:

import { mcpTool, credential, MCPTransportType } from '@inkeep/agents-sdk';
import { CredentialStoreType } from '@inkeep/agents-core';

// Define a credential that pulls from environment variables
const inkeepApiKeyCredential = credential({
  id: 'inkeep-api-key',
  type: CredentialStoreType.memory,
  credentialStoreId: 'memory-default',
  retrievalParams: {
    key: 'INKEEP_API_KEY',
  },
});

// Reference the credential object
const inkeepAnalyticsTool = mcpTool({
  id: 'inkeep-analytics',
  name: 'inkeep_analytics',
  description: 'Get the latest stats from the Inkeep Analytics dashboard',
  serverUrl: 'https://analytics.inkeep.com/mcp',
  credentialReference: inkeepApiKeyCredential, // Reference to credential object
  transport: {
    type: MCPTransportType.streamableHttp,
  },
});

Best Practices

Production Deployments

Use credential IDs: Always use credentialReferenceId with credentials created through the UI
Secure storage: Credentials are encrypted and managed centrally
Team collaboration: Credentials can be shared across team members

Development Workflows

Environment credentials: Use credentialReference with environment-based credentials
Local development: Define credentials in your environments/*.env.ts files
CI/CD integration: Environment variables can be managed by your deployment pipeline

Environment Integration

You can also define credentials in your environment files:

// environments/development.env.ts
import { registerEnvironmentSettings } from '@inkeep/agents-sdk';
import { CredentialStoreType } from '@inkeep/agents-core';

export const development = registerEnvironmentSettings({
  credentials: {
    'openai-dev': {
      id: 'openai-dev',
      type: CredentialStoreType.memory,
      credentialStoreId: 'memory-default',
      retrievalParams: {
        key: 'OPENAI_API_KEY_DEV',
      },
    },
    'inkeep-api-dev': {
      id: 'inkeep-api-dev',
      type: CredentialStoreType.memory,
      credentialStoreId: 'memory-default',
      retrievalParams: {
        key: 'INKEEP_API_KEY_DEV',
      },
    },
  },
});

Then reference them in your tools:

// tools/analytics-tool.ts
import { mcpTool, MCPTransportType } from '@inkeep/agents-sdk';

export const analyticsTool = mcpTool({
  id: 'analytics',
  name: 'analytics_tool',
  description: 'Access analytics data',
  serverUrl: 'https://analytics.example.com/mcp',
  credentialReferenceId: 'inkeep-api-dev', // References environment credential
  transport: {
    type: MCPTransportType.streamableHttp,
  },
});

On this page