You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-**Credential stores** handle the actual storage and retrieval of credential data
13
+
-**Credential references** define how to find and use stored credentials
14
+
-**TypeScript SDK vs Visual Builder** offer different creation methods depending on the credential type
12
15
13
-
## Step 2: Retrieve the credential reference id from the URLs
16
+
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.
14
17
15
-
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.
18
+
**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.
16
19
17
-
## Step 3: Reference the credential when creating an MCP tool
20
+
## Credential Store Types
18
21
19
-
There are two ways to reference credentials in your MCP tools:
22
+
The framework supports three credential store types, each suited for different authentication patterns.
20
23
21
-
### Option 1: Reference by Credential ID (Recommended)
24
+
### Memory Store
25
+
**Common use case**: Simple API keys and bearer tokens stored in environment variables. Configured directly through the TypeScript SDK.
22
26
23
-
When you create a credential through the UI, you get a credential reference ID that you can use directly:
27
+
- Credentials retrieved from environment variables at runtime
28
+
- Suitable for both development and production environments
29
+
- Direct configuration via `credential()` function in TypeScript SDK
**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.
34
+
35
+
- Managed through Nango (self-hosted or cloud)
36
+
- Supports various authentication methods: OAuth2.0, API keys, basic auth, and more
37
+
- Can provide additional metadata headers passed to MCP servers
38
+
- Requires OAuth setup through Visual Builder
39
+
40
+
### Keychain Store
41
+
**Common use case**: Locally stored OAuth tokens from OAuth2.1/PKCE flows. Credentials configured through Visual Builder.
42
+
43
+
- Credentials stored in native OS keychain (macOS Keychain Access, Windows Credential Manager, Linux Secret Service)
44
+
- Mainly used locally for development with OAuth services
45
+
- Requires OAuth setup through Visual Builder
42
46
43
-
For development workflows, you can define credentials that reference environment variables:
//Define a credential that pulls from environment variables
50
-
constinkeepApiKeyCredential=credential({
51
-
id: 'inkeep-api-key',
52
-
type: CredentialStoreType.memory,
55
+
//Step 1: Create the credential
56
+
conststripeCredential=credential({
57
+
id: 'stripe-credential',
58
+
type: CredentialStoreType.memory,// Memory store
53
59
credentialStoreId: 'memory-default',
54
60
retrievalParams: {
55
-
key: 'INKEEP_API_KEY',
61
+
key: 'STRIPE_API_KEY', // STRIPE_API_KEY=your-stripe-key should be set as an environment variable (.env file)
56
62
},
57
63
});
58
64
59
-
// Reference the credential object
60
-
const inkeepAnalyticsTool =mcpTool({
61
-
id: 'inkeep-analytics',
62
-
name: 'inkeep_analytics',
63
-
description: 'Get the latest stats from the Inkeep Analytics dashboard',
64
-
serverUrl: 'https://analytics.inkeep.com/mcp',
65
-
credentialReference: inkeepApiKeyCredential, // Reference to credential object
66
-
transport: {
67
-
type: MCPTransportType.streamableHttp,
68
-
},
65
+
// Step 2: Use credential in MCP tool
66
+
const stripeTool =mcpTool({
67
+
id: 'stripe-tool',
68
+
name: 'Stripe Tool',
69
+
description: 'Access Stripe payment services',
70
+
serverUrl: 'https://mcp.stripe.com',
71
+
credential: stripeCredential, // Reference the credential
72
+
});
73
+
74
+
// Step 3: Add tool to agent
75
+
const paymentAgent =agent({
76
+
id: 'payment-agent',
77
+
name: 'Payment Agent',
78
+
description: 'Handles payment processing',
79
+
prompt: 'You handle payment-related requests using the Stripe service.',
80
+
tools: () => [stripeTool],
69
81
});
70
82
```
71
83
72
-
## Best Practices
84
+
## Configuration Options
73
85
74
-
### Production Deployments
75
-
-**Use credential IDs**: Always use `credentialReferenceId` with credentials created through the UI
76
-
-**Secure storage**: Credentials are encrypted and managed centrally
77
-
-**Team collaboration**: Credentials can be shared across team members
86
+
### Credential Configuration
78
87
79
-
### Development Workflows
80
-
-**Environment credentials**: Use `credentialReference` with environment-based credentials
81
-
-**Local development**: Define credentials in your `environments/*.env.ts` files
82
-
-**CI/CD integration**: Environment variables can be managed by your deployment pipeline
88
+
| Parameter | Type | Required | Description |
89
+
|-----------|------|----------|-------------|
90
+
|`id`| string | Yes | Unique identifier for the credential |
91
+
|`type`| CredentialStoreType | Yes | Type of credential store (memory, nango, or keychain) |
92
+
|`credentialStoreId`| string | Yes | Identifier for the specific credential store instance |
93
+
|`retrievalParams`| object | Yes | Parameters for retrieving the credential from the store. See below for more details. |
83
94
84
-
### Environment Integration
95
+
### Retrieval Parameters by Store Type
96
+
97
+
**Memory store** credentials:
98
+
```typescript
99
+
retrievalParams: {
100
+
"key": "<environment-variable-name>", // where <environment-variable-name> is the name of the environment variable that contains the credential value
101
+
}
102
+
```
103
+
104
+
**Nango store** credentials (created through the Visual Builder - OAuth2.1/PKCE flow or Bearer authentication flow):
105
+
```typescript
106
+
// OAuth2.1/PKCE flow
107
+
retrievalParams: {
108
+
"connectionId": "oauth_token_<toolId>", // where <toolId> is the id of the MCP tool the credential is associated with
109
+
"providerConfigKey": "oauth_token_<toolId>",
110
+
"provider": "private-api-bearer",
111
+
"authMode": "API_KEY"
112
+
}
113
+
114
+
// Bearer authentication
115
+
retrievalParams: {
116
+
"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
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](/typescript-sdk/cli-reference#inkeep-push)`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.
0 commit comments