Skip to content

Commit cb3a9c0

Browse files
amithkkamithkk
committed
docs
1 parent e39acbc commit cb3a9c0

26 files changed

+4282
-217
lines changed

‎docs/auth/api-key.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# API Key Authentication
2+
3+
API Key authentication allows you to pass in an API Key as a header to the MCP server for authentication
4+
5+
## Basic Usage
6+
7+
```python
8+
from mcpadapt.auth import ApiKeyAuthProvider
9+
from mcpadapt.core import MCPAdapt
10+
from mcpadapt.smolagents_adapter import SmolAgentsAdapter
11+
12+
# Create API Key provider
13+
api_key_provider = ApiKeyAuthProvider(
14+
header_name="X-API-Key",
15+
header_value="your-api-key-here"
16+
)
17+
18+
with MCPAdapt(
19+
serverparams={"url": "https://api.example.com/mcp", "transport": "streamable-http"},
20+
adapter=SmolAgentsAdapter(),
21+
auth_provider=api_key_provider,
22+
) as tools:
23+
print(f"Connected with {len(tools)} tools")
24+
```
25+
26+
## Custom Header Names
27+
28+
Different APIs use different header names for API keys:
29+
30+
```python
31+
from mcpadapt.auth import ApiKeyAuthProvider
32+
33+
# Common API key header variations
34+
providers = [
35+
ApiKeyAuthProvider("X-API-Key", "key123"), # Most common
36+
ApiKeyAuthProvider("Authorization", "key123"), # Simple auth header
37+
ApiKeyAuthProvider("X-Auth-Token", "key123"), # Auth token variant
38+
ApiKeyAuthProvider("X-Custom-Auth", "key123"), # Custom header
39+
]
40+
```
41+
42+
## Environment Variables
43+
44+
Store API keys securely using environment variables:
45+
46+
```python
47+
import os
48+
from mcpadapt.auth import ApiKeyAuthProvider
49+
50+
# Load API key from environment
51+
api_key = os.getenv("MY_API_KEY")
52+
if not api_key:
53+
raise ValueError("MY_API_KEY environment variable is required")
54+
55+
api_key_provider = ApiKeyAuthProvider(
56+
header_name="X-API-Key",
57+
header_value=api_key
58+
)
59+
```
60+
61+
## Multiple APIs with Different Keys
62+
63+
Use different API keys for different MCP servers:
64+
65+
```python
66+
import os
67+
from mcpadapt.auth import ApiKeyAuthProvider
68+
from mcpadapt.core import MCPAdapt
69+
from mcpadapt.smolagents_adapter import SmolAgentsAdapter
70+
71+
# Different API keys for different services
72+
auth_providers = [
73+
ApiKeyAuthProvider("X-API-Key", os.getenv("SERVICE_A_KEY")),
74+
ApiKeyAuthProvider("X-Auth-Token", os.getenv("SERVICE_B_KEY")),
75+
None, # No authentication for third service
76+
]
77+
78+
server_configs = [
79+
{"url": "https://service-a.com/mcp", "transport": "streamable-http"},
80+
{"url": "https://service-b.com/mcp", "transport": "streamable-http"},
81+
{"url": "http://localhost:8000/sse"},
82+
]
83+
84+
with MCPAdapt(
85+
serverparams=server_configs,
86+
adapter=SmolAgentsAdapter(),
87+
auth_provider=auth_providers,
88+
) as tools:
89+
print(f"Connected to {len(server_configs)} servers")
90+
```
91+
92+
## API Key Formats
93+
94+
### Simple API Key
95+
96+
```python
97+
ApiKeyAuthProvider("X-API-Key", "abc123def456")
98+
```
99+
100+
### Prefixed API Key
101+
102+
```python
103+
ApiKeyAuthProvider("X-API-Key", "Bearer abc123def456")
104+
ApiKeyAuthProvider("Authorization", "API-Key abc123def456")
105+
```
106+
107+
### Base64 Encoded Credentials
108+
109+
```python
110+
import base64
111+
112+
credentials = base64.b64encode(b"username:password").decode()
113+
ApiKeyAuthProvider("Authorization", f"Basic {credentials}")
114+
```
115+
116+
## Best Practices
117+
118+
### Security
119+
- Never hard-code API keys in source code
120+
- Use environment variables or secure configuration files
121+
- Rotate API keys regularly
122+
- Use the principle of least privilege for API key permissions
123+
124+
### Configuration
125+
- Use descriptive environment variable names
126+
- Document required API keys in your README
127+
- Provide clear error messages for missing keys
128+
- Validate API key format before using
129+
130+
## Integration Examples
131+
132+
### With Different Frameworks
133+
134+
```python
135+
# SmolAgents
136+
from mcpadapt.smolagents_adapter import SmolAgentsAdapter
137+
adapter = SmolAgentsAdapter()
138+
139+
# CrewAI
140+
from mcpadapt.crewai_adapter import CrewAIAdapter
141+
adapter = CrewAIAdapter()
142+
143+
# LangChain
144+
from mcpadapt.langchain_adapter import LangChainAdapter
145+
adapter = LangChainAdapter()
146+
147+
# All use the same API key provider
148+
api_key_provider = ApiKeyAuthProvider("X-API-Key", os.getenv("API_KEY"))
149+
```

‎docs/auth/bearer-token.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Bearer Token Authentication
2+
3+
Bearer token authentication uses standard Authorization headers with Bearer tokens for MCP server authentication.
4+
5+
## Basic Usage
6+
7+
```python
8+
from mcpadapt.auth import BearerAuthProvider
9+
from mcpadapt.core import MCPAdapt
10+
from mcpadapt.smolagents_adapter import SmolAgentsAdapter
11+
12+
# Create Bearer token provider
13+
bearer_provider = BearerAuthProvider(token="your-bearer-token")
14+
15+
with MCPAdapt(
16+
serverparams={"url": "https://api.example.com/mcp", "transport": "streamable-http"},
17+
adapter=SmolAgentsAdapter(),
18+
auth_provider=bearer_provider,
19+
) as tools:
20+
print(f"Connected with {len(tools)} tools")
21+
```
22+
23+
## JWT Tokens
24+
25+
Bearer tokens are commonly used with JWT (JSON Web Tokens):
26+
27+
```python
28+
from mcpadapt.auth import BearerAuthProvider
29+
30+
# JWT token example
31+
jwt_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
32+
bearer_provider = BearerAuthProvider(token=jwt_token)
33+
```
34+
35+
## Environment Variables
36+
37+
Store bearer tokens securely:
38+
39+
```python
40+
import os
41+
from mcpadapt.auth import BearerAuthProvider
42+
43+
# Load token from environment
44+
bearer_token = os.getenv("BEARER_TOKEN")
45+
if not bearer_token:
46+
raise ValueError("BEARER_TOKEN environment variable is required")
47+
48+
bearer_provider = BearerAuthProvider(token=bearer_token)
49+
```
50+
51+
## Multiple Services
52+
53+
Use different bearer tokens for different MCP servers:
54+
55+
```python
56+
import os
57+
from mcpadapt.auth import BearerAuthProvider
58+
from mcpadapt.core import MCPAdapt
59+
from mcpadapt.smolagents_adapter import SmolAgentsAdapter
60+
61+
# Different tokens for different services
62+
auth_providers = [
63+
BearerAuthProvider(os.getenv("SERVICE_A_TOKEN")),
64+
BearerAuthProvider(os.getenv("SERVICE_B_TOKEN")),
65+
None, # No authentication for third service
66+
]
67+
68+
server_configs = [
69+
{"url": "https://service-a.com/mcp", "transport": "streamable-http"},
70+
{"url": "https://service-b.com/mcp", "transport": "streamable-http"},
71+
{"url": "http://localhost:8000/sse"},
72+
]
73+
74+
with MCPAdapt(
75+
serverparams=server_configs,
76+
adapter=SmolAgentsAdapter(),
77+
auth_provider=auth_providers,
78+
) as tools:
79+
print(f"Connected to {len(server_configs)} servers")
80+
```
81+
82+
## Token Formats
83+
84+
Bearer tokens can have different formats:
85+
86+
```python
87+
from mcpadapt.auth import BearerAuthProvider
88+
89+
# Standard JWT
90+
BearerAuthProvider("eyJhbGciOiJIUzI1NiIs...")
91+
92+
# Simple token
93+
BearerAuthProvider("abc123def456ghi789")
94+
95+
# API-specific format
96+
BearerAuthProvider("sk-1234567890abcdef")
97+
```
98+
99+
## Best Practices
100+
101+
### Security
102+
- Never hard-code bearer tokens in source code
103+
- Use environment variables or secure configuration management
104+
- Implement token rotation when possible
105+
- Monitor token expiration and refresh as needed
106+
107+
### Configuration
108+
- Use descriptive environment variable names
109+
- Validate token format before using
110+
- Handle token expiration gracefully
111+
- Log authentication failures for debugging
112+
113+
## Integration Examples
114+
115+
### With Different Frameworks
116+
117+
```python
118+
from mcpadapt.auth import BearerAuthProvider
119+
import os
120+
121+
# Same bearer provider works with all frameworks
122+
bearer_provider = BearerAuthProvider(os.getenv("BEARER_TOKEN"))
123+
124+
# SmolAgents
125+
from mcpadapt.smolagents_adapter import SmolAgentsAdapter
126+
adapter = SmolAgentsAdapter()
127+
128+
# CrewAI
129+
from mcpadapt.crewai_adapter import CrewAIAdapter
130+
adapter = CrewAIAdapter()
131+
132+
# LangChain
133+
from mcpadapt.langchain_adapter import LangChainAdapter
134+
adapter = LangChainAdapter()
135+
```

0 commit comments

Comments
 (0)