mirror of
https://github.com/OpenHands/OpenHands.git
synced 2025-12-26 05:48:36 +08:00
Update docs (#11224)
This commit is contained in:
mamoodi
GitHub
parent
aab6f4127c
commit
025ac7672f
2
.github/workflows/stale.yml
vendored
2
.github/workflows/stale.yml
vendored
@ -19,4 +19,4 @@ jobs:
|
|||||||
close-issue-message: 'This issue was automatically closed due to 50 days of inactivity. We do this to help keep the issues somewhat manageable and focus on active issues.'
|
close-issue-message: 'This issue was automatically closed due to 50 days of inactivity. We do this to help keep the issues somewhat manageable and focus on active issues.'
|
||||||
close-pr-message: 'This PR was closed because it had no activity for 50 days. If you feel this was closed in error, and you would like to continue the PR, please resubmit or let us know.'
|
close-pr-message: 'This PR was closed because it had no activity for 50 days. If you feel this was closed in error, and you would like to continue the PR, please resubmit or let us know.'
|
||||||
days-before-close: 10
|
days-before-close: 10
|
||||||
operations-per-run: 150
|
operations-per-run: 300
|
||||||
|
|||||||
@ -3,18 +3,16 @@
|
|||||||
"theme": "mint",
|
"theme": "mint",
|
||||||
"name": "All Hands Docs",
|
"name": "All Hands Docs",
|
||||||
"colors": {
|
"colors": {
|
||||||
"primary": "#99873c",
|
"primary": "#99873c"
|
||||||
"light": "#ffe165",
|
|
||||||
"dark": "#ffe165"
|
|
||||||
},
|
},
|
||||||
"background": {
|
"background": {
|
||||||
"color": {
|
"color": {
|
||||||
"light": "#f7f3ee",
|
"light": "#f7f3ee"
|
||||||
"dark": "#0B0D0E"
|
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
"appearance": {
|
"appearance": {
|
||||||
"default": "light"
|
"default": "light",
|
||||||
|
"strict": true
|
||||||
},
|
},
|
||||||
"favicon": "/logo-square.png",
|
"favicon": "/logo-square.png",
|
||||||
"navigation": {
|
"navigation": {
|
||||||
@ -215,8 +213,7 @@
|
|||||||
"footer": {
|
"footer": {
|
||||||
"socials": {
|
"socials": {
|
||||||
"slack": "https://all-hands.dev/joinslack",
|
"slack": "https://all-hands.dev/joinslack",
|
||||||
"github": "https://github.com/All-Hands-AI/OpenHands",
|
"github": "https://github.com/All-Hands-AI/OpenHands"
|
||||||
"discord": "https://discord.gg/ESHStjSjD4"
|
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
"contextual": {
|
"contextual": {
|
||||||
|
|||||||
@ -4,7 +4,8 @@ description: OpenHands - Code Less, Make More
|
|||||||
icon: book-open
|
icon: book-open
|
||||||
mode: wide
|
mode: wide
|
||||||
---
|
---
|
||||||
Use AI to tackle the toil in your backlog. Our agents have all the same tools as a human developer: they can modify code, run commands, browse the web, call APIs, and yes-even copy code snippets from StackOverflow.
|
Use AI to tackle the toil in your backlog. Our agents have all the same tools as a human developer:
|
||||||
|
they can modify code, run commands, browse the web, call APIs, and yes-even copy code snippets from StackOverflow.
|
||||||
|
|
||||||
<iframe
|
<iframe
|
||||||
className="w-full aspect-video"
|
className="w-full aspect-video"
|
||||||
|
|||||||
@ -17,96 +17,87 @@ To use the OpenHands Cloud API, you'll need to generate an API key:
|
|||||||
4. Give your key a descriptive name (Example: "Development" or "Production") and select `Create`.
|
4. Give your key a descriptive name (Example: "Development" or "Production") and select `Create`.
|
||||||
5. Copy the generated API key and store it securely. It will only be shown once.
|
5. Copy the generated API key and store it securely. It will only be shown once.
|
||||||
|
|
||||||
## API Usage
|
## API Usage Example
|
||||||
|
|
||||||
### Starting a New Conversation
|
### Starting a New Conversation
|
||||||
|
|
||||||
To start a new conversation with OpenHands to perform a task, you'll need to make a POST request to the conversation endpoint.
|
To start a new conversation with OpenHands to perform a task,
|
||||||
|
[you'll need to make a POST request to the conversation endpoint](/api-reference/new-conversation).
|
||||||
|
|
||||||
#### Request Parameters
|
<Tabs>
|
||||||
|
<Tab title="cURL">
|
||||||
|
```bash
|
||||||
|
curl -X POST "https://app.all-hands.dev/api/conversations" \
|
||||||
|
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"initial_user_msg": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
|
||||||
|
"repository": "yourusername/your-repo"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
</Tab>
|
||||||
|
<Tab title="Python (with requests)">
|
||||||
|
```python
|
||||||
|
import requests
|
||||||
|
|
||||||
| Parameter | Type | Required | Description |
|
api_key = "YOUR_API_KEY"
|
||||||
|--------------------|----------|----------|------------------------------------------------------------------------------------------------------|
|
url = "https://app.all-hands.dev/api/conversations"
|
||||||
| `initial_user_msg` | string | Yes | The initial message to start the conversation. |
|
|
||||||
| `repository` | string | No | Git repository name to provide context in the format `owner/repo`. You must have access to the repo. |
|
|
||||||
|
|
||||||
#### Examples
|
headers = {
|
||||||
|
"Authorization": f"Bearer {api_key}",
|
||||||
|
"Content-Type": "application/json"
|
||||||
<Accordion title="cURL">
|
|
||||||
```bash
|
|
||||||
curl -X POST "https://app.all-hands.dev/api/conversations" \
|
|
||||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{
|
|
||||||
"initial_user_msg": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
|
|
||||||
"repository": "yourusername/your-repo"
|
|
||||||
}'
|
|
||||||
```
|
|
||||||
</Accordion>
|
|
||||||
|
|
||||||
<Accordion title="Python (with requests)">
|
|
||||||
```python
|
|
||||||
import requests
|
|
||||||
|
|
||||||
api_key = "YOUR_API_KEY"
|
|
||||||
url = "https://app.all-hands.dev/api/conversations"
|
|
||||||
|
|
||||||
headers = {
|
|
||||||
"Authorization": f"Bearer {api_key}",
|
|
||||||
"Content-Type": "application/json"
|
|
||||||
}
|
|
||||||
|
|
||||||
data = {
|
|
||||||
"initial_user_msg": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
|
|
||||||
"repository": "yourusername/your-repo"
|
|
||||||
}
|
|
||||||
|
|
||||||
response = requests.post(url, headers=headers, json=data)
|
|
||||||
conversation = response.json()
|
|
||||||
|
|
||||||
print(f"Conversation Link: https://app.all-hands.dev/conversations/{conversation['conversation_id']}")
|
|
||||||
print(f"Status: {conversation['status']}")
|
|
||||||
```
|
|
||||||
</Accordion>
|
|
||||||
|
|
||||||
<Accordion title="TypeScript/JavaScript (with fetch)">
|
|
||||||
```typescript
|
|
||||||
const apiKey = "YOUR_API_KEY";
|
|
||||||
const url = "https://app.all-hands.dev/api/conversations";
|
|
||||||
|
|
||||||
const headers = {
|
|
||||||
"Authorization": `Bearer ${apiKey}`,
|
|
||||||
"Content-Type": "application/json"
|
|
||||||
};
|
|
||||||
|
|
||||||
const data = {
|
|
||||||
initial_user_msg: "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
|
|
||||||
repository: "yourusername/your-repo"
|
|
||||||
};
|
|
||||||
|
|
||||||
async function startConversation() {
|
|
||||||
try {
|
|
||||||
const response = await fetch(url, {
|
|
||||||
method: "POST",
|
|
||||||
headers: headers,
|
|
||||||
body: JSON.stringify(data)
|
|
||||||
});
|
|
||||||
|
|
||||||
const conversation = await response.json();
|
|
||||||
|
|
||||||
console.log(`Conversation Link: https://app.all-hands.dev/conversations/${conversation.id}`);
|
|
||||||
console.log(`Status: ${conversation.status}`);
|
|
||||||
|
|
||||||
return conversation;
|
|
||||||
} catch (error) {
|
|
||||||
console.error("Error starting conversation:", error);
|
|
||||||
}
|
}
|
||||||
}
|
|
||||||
|
|
||||||
startConversation();
|
data = {
|
||||||
```
|
"initial_user_msg": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
|
||||||
</Accordion>
|
"repository": "yourusername/your-repo"
|
||||||
|
}
|
||||||
|
|
||||||
|
response = requests.post(url, headers=headers, json=data)
|
||||||
|
conversation = response.json()
|
||||||
|
|
||||||
|
print(f"Conversation Link: https://app.all-hands.dev/conversations/{conversation['conversation_id']}")
|
||||||
|
print(f"Status: {conversation['status']}")
|
||||||
|
```
|
||||||
|
</Tab>
|
||||||
|
<Tab title="TypeScript/JavaScript (with fetch)">
|
||||||
|
```typescript
|
||||||
|
const apiKey = "YOUR_API_KEY";
|
||||||
|
const url = "https://app.all-hands.dev/api/conversations";
|
||||||
|
|
||||||
|
const headers = {
|
||||||
|
"Authorization": `Bearer ${apiKey}`,
|
||||||
|
"Content-Type": "application/json"
|
||||||
|
};
|
||||||
|
|
||||||
|
const data = {
|
||||||
|
initial_user_msg: "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
|
||||||
|
repository: "yourusername/your-repo"
|
||||||
|
};
|
||||||
|
|
||||||
|
async function startConversation() {
|
||||||
|
try {
|
||||||
|
const response = await fetch(url, {
|
||||||
|
method: "POST",
|
||||||
|
headers: headers,
|
||||||
|
body: JSON.stringify(data)
|
||||||
|
});
|
||||||
|
|
||||||
|
const conversation = await response.json();
|
||||||
|
|
||||||
|
console.log(`Conversation Link: https://app.all-hands.dev/conversations/${conversation.id}`);
|
||||||
|
console.log(`Status: ${conversation.status}`);
|
||||||
|
|
||||||
|
return conversation;
|
||||||
|
} catch (error) {
|
||||||
|
console.error("Error starting conversation:", error);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
startConversation();
|
||||||
|
```
|
||||||
|
</Tab>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
#### Response
|
#### Response
|
||||||
|
|
||||||
@ -125,42 +116,6 @@ You may receive an `AuthenticationError` if:
|
|||||||
- You provided the wrong repository name.
|
- You provided the wrong repository name.
|
||||||
- You don't have access to the repository.
|
- You don't have access to the repository.
|
||||||
|
|
||||||
|
|
||||||
### Retrieving Conversation Status
|
|
||||||
|
|
||||||
You can check the status of a conversation by making a GET request to the conversation endpoint.
|
|
||||||
|
|
||||||
#### Endpoint
|
|
||||||
|
|
||||||
```
|
|
||||||
GET https://app.all-hands.dev/api/conversations/{conversation_id}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Example
|
|
||||||
|
|
||||||
<Accordion title="cURL">
|
|
||||||
```bash
|
|
||||||
curl -X GET "https://app.all-hands.dev/api/conversations/{conversation_id}" \
|
|
||||||
-H "Authorization: Bearer YOUR_API_KEY"
|
|
||||||
```
|
|
||||||
</Accordion>
|
|
||||||
|
|
||||||
#### Response
|
|
||||||
|
|
||||||
The response is formatted as follows:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"conversation_id":"abc1234",
|
|
||||||
"title":"Update README.md",
|
|
||||||
"created_at":"2025-04-29T15:13:51.370706Z",
|
|
||||||
"last_updated_at":"2025-04-29T15:13:57.199210Z",
|
|
||||||
"status":"RUNNING",
|
|
||||||
"selected_repository":"yourusername/your-repo",
|
|
||||||
"trigger":"gui"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Rate Limits
|
## Rate Limits
|
||||||
|
|
||||||
If you have too many conversations running at once, older conversations will be paused to limit the number of concurrent conversations.
|
If you have too many conversations running at once, older conversations will be paused to limit the number of concurrent conversations.
|
||||||
|
|||||||
@ -1,8 +1,10 @@
|
|||||||
---
|
---
|
||||||
title: "Pro Subscription"
|
title: "Pro Subscription"
|
||||||
description: "Learn about OpenHands Cloud Pro Subscription features and pricing"
|
description: "Learn about OpenHands Cloud Pro Subscription features and pricing."
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
The OpenHands Pro Subscription unlocks additional features and better pricing when you run OpenHands conversations in
|
The OpenHands Pro Subscription unlocks additional features and better pricing when you run OpenHands conversations in
|
||||||
OpenHands Cloud.
|
OpenHands Cloud.
|
||||||
|
|
||||||
@ -11,13 +13,13 @@ OpenHands Cloud.
|
|||||||
All users start on the Pay-as-you-go plan and have access to these base features when they sign up:
|
All users start on the Pay-as-you-go plan and have access to these base features when they sign up:
|
||||||
|
|
||||||
* **Run multiple OpenHands conversations on OpenHands Cloud runtimes.**
|
* **Run multiple OpenHands conversations on OpenHands Cloud runtimes.**
|
||||||
* **API keys to the OpenHands LLM provider for use in OpenHands CLI or when running OpenHands on your own**
|
* **API keys to the OpenHands LLM provider for use in OpenHands CLI or when running OpenHands on your own.**
|
||||||
* **$20 in initial OpenHands Cloud credits to get started.**
|
* **$20 in initial OpenHands Cloud credits to get started.**
|
||||||
* **Support for GitHub, GitLab, Bitbucket, Slack, and more.**
|
* **Support for GitHub, GitLab, Bitbucket, Slack, and more.**
|
||||||
|
|
||||||
## What you get with a Pro Subscription
|
## What you get with a Pro Subscription
|
||||||
|
|
||||||
The $20/month Pro Subscription covers the cost of runtime compute in OpenHands Cloud, plus enables the following
|
The $20/month Pro subscription covers the cost of runtime compute in OpenHands Cloud, plus enables the following
|
||||||
features:
|
features:
|
||||||
|
|
||||||
* **Bring Your Own LLM Keys:** Bring your own API keys from OpenAI, Anthropic, Mistral, and other providers.
|
* **Bring Your Own LLM Keys:** Bring your own API keys from OpenAI, Anthropic, Mistral, and other providers.
|
||||||
|
|||||||
@ -90,7 +90,6 @@ If you would like to set things up more systematically, you can:
|
|||||||
others have encountered the same problem.
|
others have encountered the same problem.
|
||||||
2. **Join our community**: Get help from other users and developers:
|
2. **Join our community**: Get help from other users and developers:
|
||||||
- [Slack community](https://dub.sh/openhands)
|
- [Slack community](https://dub.sh/openhands)
|
||||||
- [Discord server](https://discord.gg/ESHStjSjD4)
|
|
||||||
3. **Check our troubleshooting guide**: Common issues and solutions are documented in
|
3. **Check our troubleshooting guide**: Common issues and solutions are documented in
|
||||||
[Troubleshooting](/usage/troubleshooting/troubleshooting).
|
[Troubleshooting](/usage/troubleshooting/troubleshooting).
|
||||||
4. **Report bugs**: If you've found a bug, please [create an issue](https://github.com/All-Hands-AI/OpenHands/issues/new)
|
4. **Report bugs**: If you've found a bug, please [create an issue](https://github.com/All-Hands-AI/OpenHands/issues/new)
|
||||||
|
|||||||
@ -4,16 +4,17 @@ description: Running OpenHands Cloud or running on your own.
|
|||||||
icon: rocket
|
icon: rocket
|
||||||
---
|
---
|
||||||
|
|
||||||
## OpenHands Cloud
|
<Tabs>
|
||||||
|
<Tab title="OpenHands Cloud">
|
||||||
|
The easiest way to get started with OpenHands is on OpenHands Cloud, which comes with $20 in free credits for new users.
|
||||||
|
|
||||||
The easiest way to get started with OpenHands is on OpenHands Cloud, which comes with $20 in free credits for new users.
|
To get started with OpenHands Cloud, visit [app.all-hands.dev](https://app.all-hands.dev).
|
||||||
|
|
||||||
To get started with OpenHands Cloud, visit [app.all-hands.dev](https://app.all-hands.dev).
|
For more information see [getting started with OpenHands Cloud.](/usage/cloud/openhands-cloud)
|
||||||
|
</Tab>
|
||||||
|
<Tab title="Running OpenHands on Your Own">
|
||||||
|
Run OpenHands on your local system and bring your own LLM and API key.
|
||||||
|
|
||||||
For more information see [getting started with OpenHands Cloud.](/usage/cloud/openhands-cloud)
|
For more information see [running OpenHands on your own.](/usage/local-setup)
|
||||||
|
</Tab>
|
||||||
## Running OpenHands on Your Own
|
</Tabs>
|
||||||
|
|
||||||
Run OpenHands on your local system and bring your own LLM and API key.
|
|
||||||
|
|
||||||
For more information see [running OpenHands on your own.](/usage/local-setup)
|
|
||||||
|
|||||||
@ -119,7 +119,7 @@ When started for the first time, OpenHands will prompt you to set up the LLM pro
|
|||||||
|
|
||||||
That's it! You can now start using OpenHands with the local LLM server.
|
That's it! You can now start using OpenHands with the local LLM server.
|
||||||
|
|
||||||
If you encounter any issues, let us know on [Slack](https://dub.sh/openhands) or [Discord](https://discord.gg/ESHStjSjD4).
|
If you encounter any issues, let us know on [Slack](https://dub.sh/openhands).
|
||||||
|
|
||||||
## Advanced: Alternative LLM Backends
|
## Advanced: Alternative LLM Backends
|
||||||
|
|
||||||
|
|||||||
@ -41,71 +41,71 @@ MCP configuration can be defined in:
|
|||||||
|
|
||||||
### Configuration Options
|
### Configuration Options
|
||||||
|
|
||||||
#### SSE Servers
|
<Tabs>
|
||||||
|
<Tab title="SSE Servers">
|
||||||
|
SSE servers are configured using either a string URL or an object with the following properties:
|
||||||
|
|
||||||
SSE servers are configured using either a string URL or an object with the following properties:
|
- `url` (required)
|
||||||
|
- Type: `str`
|
||||||
|
- Description: The URL of the SSE server.
|
||||||
|
|
||||||
- `url` (required)
|
- `api_key` (optional)
|
||||||
- Type: `str`
|
- Type: `str`
|
||||||
- Description: The URL of the SSE server.
|
- Description: API key for authentication.
|
||||||
|
</Tab>
|
||||||
|
<Tab title="SHTTP Servers">
|
||||||
|
SHTTP (Streamable HTTP) servers are configured using either a string URL or an object with the following properties:
|
||||||
|
|
||||||
- `api_key` (optional)
|
- `url` (required)
|
||||||
- Type: `str`
|
- Type: `str`
|
||||||
- Description: API key for authentication.
|
- Description: The URL of the SHTTP server.
|
||||||
|
|
||||||
#### SHTTP Servers
|
- `api_key` (optional)
|
||||||
|
- Type: `str`
|
||||||
|
- Description: API key for authentication.
|
||||||
|
|
||||||
SHTTP (Streamable HTTP) servers are configured using either a string URL or an object with the following properties:
|
- `timeout` (optional)
|
||||||
|
- Type: `int`
|
||||||
|
- Default: `60`
|
||||||
|
- Range: `1-3600` seconds (1 hour maximum)
|
||||||
|
- Description: Timeout in seconds for tool execution. This prevents tool calls from hanging indefinitely.
|
||||||
|
- **Use Cases:**
|
||||||
|
- **Short timeout (1-30s)**: For lightweight operations like status checks or simple queries.
|
||||||
|
- **Medium timeout (30-300s)**: For standard processing tasks like data analysis or API calls.
|
||||||
|
- **Long timeout (300-3600s)**: For heavy operations like file processing, complex calculations, or batch operations.
|
||||||
|
<Note>
|
||||||
|
This timeout only applies to individual tool calls, not server connection establishment.
|
||||||
|
</Note>
|
||||||
|
</Tab>
|
||||||
|
<Tab title="Stdio Servers">
|
||||||
|
<Note>
|
||||||
|
While stdio servers are supported, [we recommend using MCP proxies](/usage/settings/mcp-settings#configuration-examples) for
|
||||||
|
better reliability and performance.
|
||||||
|
</Note>
|
||||||
|
|
||||||
- `url` (required)
|
Stdio servers are configured using an object with the following properties:
|
||||||
- Type: `str`
|
|
||||||
- Description: The URL of the SHTTP server.
|
|
||||||
|
|
||||||
- `api_key` (optional)
|
- `name` (required)
|
||||||
- Type: `str`
|
- Type: `str`
|
||||||
- Description: API key for authentication.
|
- Description: A unique name for the server.
|
||||||
|
|
||||||
- `timeout` (optional)
|
- `command` (required)
|
||||||
- Type: `int`
|
- Type: `str`
|
||||||
- Default: `60`
|
- Description: The command to run the server.
|
||||||
- Range: `1-3600` seconds (1 hour maximum)
|
|
||||||
- Description: Timeout in seconds for tool execution. This prevents tool calls from hanging indefinitely.
|
|
||||||
- **Use Cases:**
|
|
||||||
- **Short timeout (1-30s)**: For lightweight operations like status checks or simple queries.
|
|
||||||
- **Medium timeout (30-300s)**: For standard processing tasks like data analysis or API calls.
|
|
||||||
- **Long timeout (300-3600s)**: For heavy operations like file processing, complex calculations, or batch operations.
|
|
||||||
<Note>
|
|
||||||
This timeout only applies to individual tool calls, not server connection establishment.
|
|
||||||
</Note>
|
|
||||||
|
|
||||||
#### Stdio Servers
|
- `args` (optional)
|
||||||
|
- Type: `list of str`
|
||||||
|
- Default: `[]`
|
||||||
|
- Description: Command-line arguments to pass to the server.
|
||||||
|
|
||||||
<Note>
|
- `env` (optional)
|
||||||
While stdio servers are supported, [we recommend using MCP proxies](/usage/settings/mcp-settings#configuration-examples) for
|
- Type: `dict of str to str`
|
||||||
better reliability and performance.
|
- Default: `{}`
|
||||||
</Note>
|
- Description: Environment variables to set for the server process.
|
||||||
|
</Tab>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
Stdio servers are configured using an object with the following properties:
|
#### When to Use Direct Stdio
|
||||||
|
|
||||||
- `name` (required)
|
|
||||||
- Type: `str`
|
|
||||||
- Description: A unique name for the server.
|
|
||||||
|
|
||||||
- `command` (required)
|
|
||||||
- Type: `str`
|
|
||||||
- Description: The command to run the server.
|
|
||||||
|
|
||||||
- `args` (optional)
|
|
||||||
- Type: `list of str`
|
|
||||||
- Default: `[]`
|
|
||||||
- Description: Command-line arguments to pass to the server.
|
|
||||||
|
|
||||||
- `env` (optional)
|
|
||||||
- Type: `dict of str to str`
|
|
||||||
- Default: `{}`
|
|
||||||
- Description: Environment variables to set for the server process.
|
|
||||||
|
|
||||||
##### When to Use Direct Stdio
|
|
||||||
|
|
||||||
Direct stdio connections may still be appropriate in these scenarios:
|
Direct stdio connections may still be appropriate in these scenarios:
|
||||||
- **Development and testing**: Quick prototyping of MCP servers.
|
- **Development and testing**: Quick prototyping of MCP servers.
|
||||||
@ -114,76 +114,78 @@ Direct stdio connections may still be appropriate in these scenarios:
|
|||||||
|
|
||||||
### Configuration Examples
|
### Configuration Examples
|
||||||
|
|
||||||
#### Recommended: Using Proxy Servers (SSE/HTTP)
|
<Tabs>
|
||||||
|
<Tab title="Proxy Servers (SSE/HTTP) - Recommended">
|
||||||
|
For stdio-based MCP servers, we recommend using MCP proxy tools like
|
||||||
|
[`supergateway`](https://github.com/supercorp-ai/supergateway) instead of direct stdio connections.
|
||||||
|
[SuperGateway](https://github.com/supercorp-ai/supergateway) is a popular MCP proxy that converts stdio MCP servers to
|
||||||
|
HTTP/SSE endpoints.
|
||||||
|
|
||||||
For stdio-based MCP servers, we recommend using MCP proxy tools like
|
Start the proxy servers separately:
|
||||||
[`supergateway`](https://github.com/supercorp-ai/supergateway) instead of direct stdio connections.
|
```bash
|
||||||
[SuperGateway](https://github.com/supercorp-ai/supergateway) is a popular MCP proxy that converts stdio MCP servers to
|
# Terminal 1: Filesystem server proxy
|
||||||
HTTP/SSE endpoints.
|
supergateway --stdio "npx @modelcontextprotocol/server-filesystem /" --port 8080
|
||||||
|
|
||||||
Start the proxy servers separately:
|
# Terminal 2: Fetch server proxy
|
||||||
```bash
|
supergateway --stdio "uvx mcp-server-fetch" --port 8081
|
||||||
# Terminal 1: Filesystem server proxy
|
```
|
||||||
supergateway --stdio "npx @modelcontextprotocol/server-filesystem /" --port 8080
|
|
||||||
|
|
||||||
# Terminal 2: Fetch server proxy
|
Then configure OpenHands to use the HTTP endpoint:
|
||||||
supergateway --stdio "uvx mcp-server-fetch" --port 8081
|
|
||||||
```
|
|
||||||
|
|
||||||
Then configure OpenHands to use the HTTP endpoint:
|
```toml
|
||||||
|
[mcp]
|
||||||
|
# SSE Servers - Recommended approach using proxy tools
|
||||||
|
sse_servers = [
|
||||||
|
# Basic SSE server with just a URL
|
||||||
|
"http://example.com:8080/mcp",
|
||||||
|
|
||||||
```toml
|
# SuperGateway proxy for fetch server
|
||||||
[mcp]
|
"http://localhost:8081/sse",
|
||||||
# SSE Servers - Recommended approach using proxy tools
|
|
||||||
sse_servers = [
|
|
||||||
# Basic SSE server with just a URL
|
|
||||||
"http://example.com:8080/mcp",
|
|
||||||
|
|
||||||
# SuperGateway proxy for fetch server
|
# External MCP service with authentication
|
||||||
"http://localhost:8081/sse",
|
{url="https://api.example.com/mcp/sse", api_key="your-api-key"}
|
||||||
|
]
|
||||||
|
|
||||||
# External MCP service with authentication
|
# SHTTP Servers - Modern streamable HTTP transport (recommended)
|
||||||
{url="https://api.example.com/mcp/sse", api_key="your-api-key"}
|
shttp_servers = [
|
||||||
]
|
# Basic SHTTP server with default 60s timeout
|
||||||
|
"https://api.example.com/mcp/shttp",
|
||||||
|
|
||||||
# SHTTP Servers - Modern streamable HTTP transport (recommended)
|
# Server with custom timeout for heavy operations
|
||||||
shttp_servers = [
|
{
|
||||||
# Basic SHTTP server with default 60s timeout
|
url = "https://files.example.com/mcp/shttp",
|
||||||
"https://api.example.com/mcp/shttp",
|
api_key = "your-api-key",
|
||||||
|
timeout = 1800 # 30 minutes for large file processing
|
||||||
# Server with custom timeout for heavy operations
|
|
||||||
{
|
|
||||||
url = "https://files.example.com/mcp/shttp",
|
|
||||||
api_key = "your-api-key",
|
|
||||||
timeout = 1800 # 30 minutes for large file processing
|
|
||||||
}
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Alternative: Direct Stdio Servers (Not Recommended for Production)
|
|
||||||
|
|
||||||
```toml
|
|
||||||
[mcp]
|
|
||||||
# Direct stdio servers - use only for development/testing
|
|
||||||
stdio_servers = [
|
|
||||||
# Basic stdio server
|
|
||||||
{name="fetch", command="uvx", args=["mcp-server-fetch"]},
|
|
||||||
|
|
||||||
# Stdio server with environment variables
|
|
||||||
{
|
|
||||||
name="filesystem",
|
|
||||||
command="npx",
|
|
||||||
args=["@modelcontextprotocol/server-filesystem", "/"],
|
|
||||||
env={
|
|
||||||
"DEBUG": "true"
|
|
||||||
}
|
}
|
||||||
}
|
]
|
||||||
]
|
```
|
||||||
```
|
</Tab>
|
||||||
|
<Tab title="Direct Stdio Servers">
|
||||||
|
<Note>
|
||||||
|
This setup is not Recommended for production.
|
||||||
|
</Note>
|
||||||
|
```toml
|
||||||
|
[mcp]
|
||||||
|
# Direct stdio servers - use only for development/testing
|
||||||
|
stdio_servers = [
|
||||||
|
# Basic stdio server
|
||||||
|
{name="fetch", command="uvx", args=["mcp-server-fetch"]},
|
||||||
|
|
||||||
For production use, we recommend using proxy tools like SuperGateway.
|
# Stdio server with environment variables
|
||||||
|
{
|
||||||
|
name="filesystem",
|
||||||
|
command="npx",
|
||||||
|
args=["@modelcontextprotocol/server-filesystem", "/"],
|
||||||
|
env={
|
||||||
|
"DEBUG": "true"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
### Other Proxy Tools
|
For production use, we recommend using proxy tools like SuperGateway.
|
||||||
|
</Tab>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
Other options include:
|
Other options include:
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user