Credentials

Securely store and retrieve authentication credentials for MCP servers.

How Credential Storage Works

Key concepts:

• Credential stores handle the actual storage and retrieval of credential data
• Credential references define how to find and use stored credentials
• TypeScript SDK vs Visual Builder offer different creation methods depending on the credential type

The framework uses a system that stores references to credentials and retrieves the actual credential values at runtime. When you define a credential, you're creating a reference that tells the system where and how to find the credential data. The actual credential is fetched at runtime and injected into the authorization headers for MCP tools.

Key limitations: The TypeScript SDK can only directly create Memory store credentials. Nango and Keychain stores require OAuth authorization flows with user interaction, which are handled through the Visual Builder interface.

Credential Store Types

The framework supports three credential store types, each suited for different authentication patterns.

Memory Store

Common use case: Simple API keys and bearer tokens stored in environment variables. Configured directly through the TypeScript SDK.

• Credentials retrieved from environment variables at runtime
• Suitable for both development and production environments
• Direct configuration via credential() function in TypeScript SDK

Nango Store

Common use case: OAuth tokens from OAuth2.1/PKCE flows, complex OAuth flows, integrating with external services (Slack, GitHub, Google, etc.), when extra headers are needed, etc. Credentials configured through Visual Builder.

• Managed through Nango (self-hosted or cloud)
• Supports various authentication methods: OAuth2.0, API keys, basic auth, and more
• Can provide additional metadata headers passed to MCP servers
• Requires OAuth setup through Visual Builder

Keychain Store

Common use case: Locally stored OAuth tokens from OAuth2.1/PKCE flows. Credentials configured through Visual Builder.

• Credentials stored in native OS keychain (macOS Keychain Access, Windows Credential Manager, Linux Secret Service)
• Mainly used locally for development with OAuth services
• Requires OAuth setup through Visual Builder

Creating and Using Credentials

Basic Setup Example

import { mcpTool, credential, agent, agentGraph } from "@inkeep/agents-sdk";
import { CredentialStoreType } from "@inkeep/agents-core";

// Step 1: Create the credential
const stripeCredential = credential({
  id: 'stripe-credential',
  type: CredentialStoreType.memory, // Memory store
  credentialStoreId: 'memory-default',
  retrievalParams: {
    key: 'STRIPE_API_KEY', // STRIPE_API_KEY=your-stripe-key should be set as an environment variable (.env file)
  },
});

// Step 2: Use credential in MCP tool
const stripeTool = mcpTool({
  id: 'stripe-tool',
  name: 'Stripe Tool',
  description: 'Access Stripe payment services',
  serverUrl: 'https://mcp.stripe.com',
  credential: stripeCredential, // Reference the credential
});

// Step 3: Add tool to agent
const paymentAgent = agent({
  id: 'payment-agent',
  name: 'Payment Agent',
  description: 'Handles payment processing',
  prompt: 'You handle payment-related requests using the Stripe service.',
  tools: () => [stripeTool],
});

Configuration Options

Credential Configuration

Retrieval Parameters by Store Type

Memory store credentials:

retrievalParams: {
  "key": "<environment-variable-name>", // where <environment-variable-name> is the name of the environment variable that contains the credential value
}

Nango store credentials (created through the Visual Builder - OAuth2.1/PKCE flow or Bearer authentication flow):

// OAuth2.1/PKCE flow
retrievalParams: {
  "connectionId": "oauth_token_<toolId>", // where <toolId> is the id of the MCP tool the credential is associated with
  "providerConfigKey": "oauth_token_<toolId>",
  "provider": "private-api-bearer",
  "authMode": "API_KEY"
}

// Bearer authentication 
retrievalParams: {
  "connectionId": "<id-given-to-bearer-api-key>", // where <id-given-to-bearer-api-key> is the id given to the bearer api key created in through the Visual Builder
  "providerConfigKey": "<id-given-to-bearer-api-key>",
  "provider": "private-api-bearer",
  "authMode": "API_KEY"
}

Keychain store credentials (created through the Visual Builder - OAuth2.1/PKCE flow):

retrievalParams: {
  "key": "oauth_token_<toolId>" // where <toolId> is the id of the MCP tool the credential is associated with
}

Environment-aware Credentials

You can also define credentials in your environment files:

Then reference them in your tools:

import { mcpTool } from "@inkeep/agents-sdk";
import { envSettings } from "../environments";

export const stripeTool = mcpTool({
  id: 'stripe-tool',
  name: 'Stripe',
  serverUrl: 'https://mcp.stripe.com/mcp',
  credential: envSettings.getEnvironmentSetting('stripe_api_key'),
});

This pattern is useful if you want to keep track of different credentials for different environments. When you push your project using the Inkeep CLI inkeep push command with the --env flag, the credentials will be loaded from the appropriate environment file. For example, if you run inkeep push --env development, the credentials will be loaded from the environments/development.env.ts file.