From 3545461e7c9a468b30afd713e8f8843b97eca5d0 Mon Sep 17 00:00:00 2001 From: rohanharikr Date: Fri, 25 Jul 2025 10:25:52 +0100 Subject: [PATCH 1/8] Enhance MCP documentation for clarity and structure - Wrap BETA label in a div for improved layout - Update installation section to highlight key features and quick installation options - Reorganize content for better flow, including a new "Getting Started" section - Add detailed installation instructions for various tools - Streamline troubleshooting and contributing sections for clarity --- pages/docs/mcp.mdx | 282 ++++++++++++++++++++++++++++----------------- 1 file changed, 175 insertions(+), 107 deletions(-) diff --git a/pages/docs/mcp.mdx b/pages/docs/mcp.mdx index 8281958..d12bfd5 100644 --- a/pages/docs/mcp.mdx +++ b/pages/docs/mcp.mdx @@ -2,27 +2,41 @@ import { Callout } from 'nextra/components' # MCP Server (BETA) -BETA +
+ BETA +
Model Context Protocol (MCP) server for creating and managing Hellō applications directly from your AI assistant. -**BETA Status**: This MCP server is currently in beta. We're actively seeking feedback and welcome contributions! Please report issues, suggest improvements, or submit pull requests to help us improve the developer experience. +**BETA Status**: This MCP server is currently in beta. We're actively seeking feedback and welcome contributions! Please report issues, suggest improvements, or submit pull requests to help improve the developer experience. ## Overview The Hellō MCP server provides a **single powerful tool** (`hello_manage_app`) that lets you create and manage your Hellō applications directly from your AI assistant, including uploading logos for both light and dark themes. -## Installation +## Key Features -| Cursor | VS Code | -|--------|---------| -| [Install MCP Server](https://cursor.com/install-mcp?name=hello-admin&config=eyJ1cmwiOiJodHRwczovL21jcC5oZWxsby5jb29wIn0K) | [Install on VS Code](vscode:mcp/install?%7B%22name%22%3A%22Hell%C5%8D%20Admin%22%2C%22url%22%3A%22https%3A//mcp.hello.coop%22%2C%22type%22%3A%22http%22%7D) | +- One powerful tool (`hello_manage_app`) for all app management actions +- Supports `create`, `update`, `read`, `create_secret`, and logo uploads +- Compatible with major AI clients: Cursor, Claude, VS Code, LM Studio, and more +- Automatically includes full developer context (user, teams, applications) +- Secure OAuth 2.1 flow with short-lived access tokens +- Supports both HTTP (remote) and STDIO (local) configurations +- Access resources such as the Logo Design Guide, Login Button Guide, Quickstart Setup, and full API documentation -### Configuration Options +## Getting Started + +You can install the Hellō MCP server manually using a simple configuration object, or use one of the quick-install options available in select tools. + +### Manual Configuration (Works in Most Tools) +> Using a supported tool like Cursor or VS Code? You can skip ahead to the Quick Installation Options below. + +Use the following configurations if you're setting up the MCP server manually or using a tool that prompts for input. + +**HTTP Transport (Remote – Recommended)** -**HTTP Transport (Remote - Recommended):** ```json { "hello-admin-http": { @@ -30,9 +44,10 @@ The Hellō MCP server provides a **single powerful tool** (`hello_manage_app`) t "type": "http" } } -``` +```` + +**NPM Package (Local)** -**NPM Package (Local):** ```json { "hello-admin-stdio": { @@ -43,124 +58,167 @@ The Hellō MCP server provides a **single powerful tool** (`hello_manage_app`) t } ``` -📖 **[Local Development Setup](https://github.com/hellocoop/MCP#local-development)** - For running from source +### Quick Installation Options +Some tools support direct install links or commands that preconfigure the MCP server for you. -## Available Tools +
+Cursor -### Core Tool: `hello_manage_app` +
+Click to install: -**The main tool for all application management** with these actions: - -- **`create`** - Create new applications with smart defaults -- **`read`** - Read application details (or profile-only without client_id) -- **`update`** - Update application settings -- **`create_secret`** - Generate OAuth client secrets -- **`upload_logo_file`** - Upload logo from base64 data -- **`upload_logo_url`** - Upload logo from URL - -**Every response includes your complete profile context:** -- Your user profile (name, email, picture) -- All your teams/organizations with roles -- All your applications with team associations -- Current team and application state - -{/* -## Usage Examples - -### Creating Your First Application - -1. **Check your profile context**: - ``` - Use hello_manage_app with action: "read" (no client_id) - ``` - -2. **Create an application**: - ``` - Use hello_manage_app with: - - action: "create" - - name: "My App" - - dev_redirect_uris: ["http://localhost:3000/callback"] - ``` - -3. **Upload a logo**: - ``` - Use hello_manage_app with: - - action: "upload_logo_url" - - client_id: "your-app-id" - - logo_url: "https://example.com/logo.png" - - logo_content_type: "image/png" - ``` - -### Managing Applications - -**Read specific application:** -``` -Use hello_manage_app with: -- action: "read" -- client_id: "your-app-id" -``` + + Install MCP Server + -**Update application:** -``` -Use hello_manage_app with: -- action: "update" -- client_id: "your-app-id" -- name: "Updated App Name" -- tos_uri: "https://example.com/terms" -``` +Or install manually via `Cursor Settings → MCP → Add new MCP Server`. Use type `http` and URL `https://mcp.hello.coop/`. + +
+
+ +
+VS Code + +
+Click to install: + + + Install on VS Code + -**Create client secret:** +Or follow the [VS Code guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) or run: + +```bash +code --add-mcp '{"name":"Hellō Admin","url":"https://mcp.hello.coop","type":"http"}' ``` -Use hello_manage_app with: -- action: "create_secret" -- client_id: "your-app-id" + +
+
+ +
+Claude Code + +
+Install using the Claude CLI: + +```bash +claude mcp add hello-admin http https://mcp.hello.coop/ ``` -*/} + +
+
+ +
+Claude Desktop + +

Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), and use the HTTP Transport config.

+ +
+ +
+Gemini CLI + +

See the [Gemini MCP Server docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson).

+ +
+ +
+Goose + +
+Click to install: + + + Install in Goose + + +Or go to `Advanced settings → Extensions → Add custom extension` and enter the HTTP config manually. + +
+
+ +
+LM Studio + +
+Click to install: + + + Add MCP Server hello-admin to LM Studio + + +Or go to `Program → Install → Edit mcp.json` and paste the standard config. + +
+
+ +
+Qodo Gen + +

In Qodo Gen: open the chat panel → Connect more tools → Add new MCP → Paste the HTTP Transport config.

+ +
+ +
+Windsurf +

Follow the [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp). Use the standard config.

+
+ +
+Run from Source +

Clone the repo and follow the instructions at: https://github.com/hellocoop/MCP#local-development

+
+ +Don’t see your tool listed? [File an issue](https://github.com/hellocoop/hello.dev/issues) and we’ll add support. + +## Available Commands + +### Core Tool: `hello_manage_app` + +This is the primary tool for managing Hellō applications. + +Supported actions: + +* `create` – Create new applications with smart defaults +* `read` – Retrieve application or profile details +* `update` – Update app settings (redirect URIs, names, etc.) +* `create_secret` – Generate OAuth client secrets +* `upload_logo_file` – Upload a logo using base64 data +* `upload_logo_url` – Upload a logo via public URL + +Each response includes: + +* Your user profile (name, email, picture) +* Your teams and organizations, along with assigned roles +* All apps associated with your teams +* Current team and app state ## Authentication -The MCP server uses OAuth 2.1 for secure authentication: +This MCP server uses OAuth 2.1 for secure authentication: 1. **OAuth Flow**: When you first use the tool, the server opens your browser 2. **Login**: Complete the login process with your Hellō account 3. **Token**: The server receives a 1-hour access token 4. **Context**: All API calls return your complete developer context - -## Available Resources - -Access comprehensive documentation and guidance: - -- **Hellō Documentation** - Complete integration documentation -- **Hellō Quickstarts** - Framework-specific setup guides -- **Hellō Logo Design Guidance** - Guide for creating theme-appropriate logos -- **Hellō Login Button Implementation** - Complete button implementation guide - ## Troubleshooting -### Common Issues +### "Authentication required" errors -**"Authentication required" errors:** -- The server will automatically prompt for login when needed -- Make sure you complete the browser-based OAuth flow +* The server will automatically prompt for login when needed +* Complete the browser-based OAuth flow when prompted -**"Application not found" errors:** -- Use `hello_manage_app` with `action: "read"` to see your applications -- Make sure you're using the correct `client_id` +### "Application not found" -**Logo upload issues:** -- Ensure `logo_content_type` matches your image format -- Supported formats: PNG, JPEG, GIF, WebP, APNG, SVG -- Keep file sizes under 100KB for best performance +* Run `hello_manage_app` with `action: "read"` to list your apps +* Double-check that you’re using the correct `client_id` -### Getting Help & Contributing +### Logo upload issues -**We want your feedback!** This MCP server is in beta and we're actively improving it. - -- **Documentation**: [MCP Server Repository](https://github.com/hellocoop/MCP) -- **Report Issues**: [GitHub Issues](https://github.com/hellocoop/MCP/issues) -- **Contribute**: [Submit Pull Requests](https://github.com/hellocoop/MCP/pulls) -- **Community**: [Join our Slack Community](https://hello-community.slack.com/join/shared_invite/zt-1eccnd2np-qJoOWBkHGnpxvBpCTtaH9g#/shared-invite/email) +* Ensure `logo_content_type` matches the file type +* Supported formats: `.png`, `.jpeg`, `.gif`, `.webp`, `.apng`, `.svg` +* Keep file sizes under 100KB for best performance ## Security & Limitations @@ -168,12 +226,22 @@ Access comprehensive documentation and guidance: - OAuth 2.1 industry-standard authentication - Short-lived tokens (1-hour expiration) - HTTPS-only API communication -- Access scoped to create, read, update. No deletion permitted. +- Access scoped to create, read, update. Deletion actions are intentionally restricted. **Current Limitations:** - Cannot delete applications (use [Hellō Console](https://console.hello.coop) for deletion) - Token requires re-authentication after 1 hour of inactivity + +## Contributing + +We welcome your feedback and contributions: + +* 📄 [MCP Server Docs](https://github.com/hellocoop/MCP) +* 🐛 [GitHub Issues](https://github.com/hellocoop/MCP/issues) +* 🔀 [Pull Requests](https://github.com/hellocoop/MCP/pulls) +* 💬 [Join our Slack Community](https://hello-community.slack.com/join/shared_invite/zt-1eccnd2np-qJoOWBkHGnpxvBpCTtaH9g#/shared-invite/email) + --- -For detailed development setup, testing, and contribution guidelines, visit the [Hellō MCP Server repository](https://github.com/hellocoop/MCP). +For local development, testing, and advanced usage, visit the full [MCP Server GitHub repo](https://github.com/hellocoop/MCP). From 12ac94eaa1bb3d42dd0ec383900e422b093da29b Mon Sep 17 00:00:00 2001 From: rohanharikr Date: Fri, 25 Jul 2025 10:27:08 +0100 Subject: [PATCH 2/8] remove emojis --- pages/docs/mcp.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pages/docs/mcp.mdx b/pages/docs/mcp.mdx index d12bfd5..f9df0fa 100644 --- a/pages/docs/mcp.mdx +++ b/pages/docs/mcp.mdx @@ -237,10 +237,10 @@ This MCP server uses OAuth 2.1 for secure authentication: We welcome your feedback and contributions: -* 📄 [MCP Server Docs](https://github.com/hellocoop/MCP) -* 🐛 [GitHub Issues](https://github.com/hellocoop/MCP/issues) -* 🔀 [Pull Requests](https://github.com/hellocoop/MCP/pulls) -* 💬 [Join our Slack Community](https://hello-community.slack.com/join/shared_invite/zt-1eccnd2np-qJoOWBkHGnpxvBpCTtaH9g#/shared-invite/email) +* [MCP Server Docs](https://github.com/hellocoop/MCP) +* [GitHub Issues](https://github.com/hellocoop/MCP/issues) +* [Pull Requests](https://github.com/hellocoop/MCP/pulls) +* [Join our Slack Community](https://hello-community.slack.com/join/shared_invite/zt-1eccnd2np-qJoOWBkHGnpxvBpCTtaH9g#/shared-invite/email) --- From 087d28532e2f3cb012dd561e60ce976e573776e7 Mon Sep 17 00:00:00 2001 From: rohanharikr Date: Fri, 25 Jul 2025 10:27:48 +0100 Subject: [PATCH 3/8] copy --- pages/docs/mcp.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/mcp.mdx b/pages/docs/mcp.mdx index f9df0fa..0eac15f 100644 --- a/pages/docs/mcp.mdx +++ b/pages/docs/mcp.mdx @@ -235,7 +235,7 @@ This MCP server uses OAuth 2.1 for secure authentication: ## Contributing -We welcome your feedback and contributions: +**We want your feedback!** This MCP server is in beta and we're actively improving it. * [MCP Server Docs](https://github.com/hellocoop/MCP) * [GitHub Issues](https://github.com/hellocoop/MCP/issues) From 4d37cf9e53cb6df2de5b1763afd7a4de967dc756 Mon Sep 17 00:00:00 2001 From: rohanharikr Date: Fri, 25 Jul 2025 10:31:13 +0100 Subject: [PATCH 4/8] Refactor MCP documentation for improved clarity and organization - Rename core tool section for better emphasis - Consolidate troubleshooting issues under a "Common Issues" heading - Enhance logo upload guidance with specific format requirements - Streamline the "Getting Help & Contributing" section with direct links to resources --- pages/docs/mcp.mdx | 40 +++++++++++++++++++--------------------- 1 file changed, 19 insertions(+), 21 deletions(-) diff --git a/pages/docs/mcp.mdx b/pages/docs/mcp.mdx index 0eac15f..3b020e6 100644 --- a/pages/docs/mcp.mdx +++ b/pages/docs/mcp.mdx @@ -173,7 +173,7 @@ Don’t see your tool listed? [File an issue](https://github.com/hellocoop/hello ## Available Commands -### Core Tool: `hello_manage_app` +### `hello_manage_app` (Core Tool) This is the primary tool for managing Hellō applications. @@ -204,21 +204,29 @@ This MCP server uses OAuth 2.1 for secure authentication: ## Troubleshooting -### "Authentication required" errors +### Common Issues -* The server will automatically prompt for login when needed -* Complete the browser-based OAuth flow when prompted +**"Authentication required" errors:** +- The server will automatically prompt for login when needed +- Make sure you complete the browser-based OAuth flow -### "Application not found" +**"Application not found" errors:** +- Use `hello_manage_app` with `action: "read"` to see your applications +- Make sure you're using the correct `client_id` -* Run `hello_manage_app` with `action: "read"` to list your apps -* Double-check that you’re using the correct `client_id` +**Logo upload issues:** +- Ensure `logo_content_type` matches your image format +- Supported formats: PNG, JPEG, GIF, WebP, APNG, SVG +- Keep file sizes under 100KB for best performance -### Logo upload issues +### Getting Help & Contributing -* Ensure `logo_content_type` matches the file type -* Supported formats: `.png`, `.jpeg`, `.gif`, `.webp`, `.apng`, `.svg` -* Keep file sizes under 100KB for best performance +**We want your feedback!** This MCP server is in beta and we're actively improving it. + +- **Documentation**: [MCP Server Repository](https://github.com/hellocoop/MCP) +- **Report Issues**: [GitHub Issues](https://github.com/hellocoop/MCP/issues) +- **Contribute**: [Submit Pull Requests](https://github.com/hellocoop/MCP/pulls) +- **Community**: [Join our Slack Community](https://hello-community.slack.com/join/shared_invite/zt-1eccnd2np-qJoOWBkHGnpxvBpCTtaH9g#/shared-invite/email) ## Security & Limitations @@ -232,16 +240,6 @@ This MCP server uses OAuth 2.1 for secure authentication: - Cannot delete applications (use [Hellō Console](https://console.hello.coop) for deletion) - Token requires re-authentication after 1 hour of inactivity - -## Contributing - -**We want your feedback!** This MCP server is in beta and we're actively improving it. - -* [MCP Server Docs](https://github.com/hellocoop/MCP) -* [GitHub Issues](https://github.com/hellocoop/MCP/issues) -* [Pull Requests](https://github.com/hellocoop/MCP/pulls) -* [Join our Slack Community](https://hello-community.slack.com/join/shared_invite/zt-1eccnd2np-qJoOWBkHGnpxvBpCTtaH9g#/shared-invite/email) - --- For local development, testing, and advanced usage, visit the full [MCP Server GitHub repo](https://github.com/hellocoop/MCP). From b544934ddbcf5ca58eb5584e99a2a03310e7a9b9 Mon Sep 17 00:00:00 2001 From: rohanharikr Date: Fri, 25 Jul 2025 21:29:10 +0100 Subject: [PATCH 5/8] Update beta label positioning and media query in CSS - Adjusted the top position of the beta label for better visibility - Reduced the width of the beta label for a more compact design - Updated media query breakpoint from 768px to 900px for improved responsiveness --- styles/index.css | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/styles/index.css b/styles/index.css index b55c2e4..c09420e 100644 --- a/styles/index.css +++ b/styles/index.css @@ -50,12 +50,12 @@ main a[target="_blank"]:after { .beta-label { position: absolute; - top: 54px; + top: 12px; right: 32px; - width: 80px; + width: 60px; } -@media screen and (min-width: 768px) { +@media screen and (min-width: 900px) { .beta-label { position: absolute; top: 32px; From b0830ae62ab6ea5c28c0d1c483aa63a67d8eadea Mon Sep 17 00:00:00 2001 From: rohanharikr Date: Fri, 25 Jul 2025 21:29:30 +0100 Subject: [PATCH 6/8] Update MCP documentation to introduce Admin MCP Server - Rename "MCP" to "Admin MCP Server" in metadata for clarity - Add comprehensive documentation for the new Admin MCP Server, including installation instructions, key features, and troubleshooting guidance - Highlight the BETA status and encourage user feedback for improvements --- pages/docs/_meta.json | 2 +- pages/docs/{mcp.mdx => admin-mcp.mdx} | 158 ++++++++++++-------------- 2 files changed, 76 insertions(+), 84 deletions(-) rename pages/docs/{mcp.mdx => admin-mcp.mdx} (72%) diff --git a/pages/docs/_meta.json b/pages/docs/_meta.json index d796bf0..3b1cfd0 100644 --- a/pages/docs/_meta.json +++ b/pages/docs/_meta.json @@ -8,7 +8,7 @@ "apis": "API References", "oidc": "OpenID Connect", "mockin": "Hellō Mockin", - "mcp": "Hellō MCP Server", + "admin-mcp": "Admin MCP Server", "comparison": "Hellō vs ___", "roadmap": "Roadmap" } \ No newline at end of file diff --git a/pages/docs/mcp.mdx b/pages/docs/admin-mcp.mdx similarity index 72% rename from pages/docs/mcp.mdx rename to pages/docs/admin-mcp.mdx index 3b020e6..1017178 100644 --- a/pages/docs/mcp.mdx +++ b/pages/docs/admin-mcp.mdx @@ -1,21 +1,19 @@ import { Callout } from 'nextra/components' -# MCP Server (BETA) +# Admin MCP Server (BETA)
BETA
-Model Context Protocol (MCP) server for creating and managing Hellō applications directly from your AI assistant. +The Admin MCP server lets you create and manage your Hellō applications directly from your AI assistant, +including uploading logos for both light and dark themes. -**BETA Status**: This MCP server is currently in beta. We're actively seeking feedback and welcome contributions! Please report issues, suggest improvements, or submit pull requests to help improve the developer experience. +This MCP server is currently in BETA. Help us improve the server by filing [issues or making suggestions](https://github.com/hellocoop/MCP/issues). -## Overview - -The Hellō MCP server provides a **single powerful tool** (`hello_manage_app`) that lets you create and manage your Hellō applications directly from your AI assistant, including uploading logos for both light and dark themes. - +{/* ## Key Features - One powerful tool (`hello_manage_app`) for all app management actions @@ -25,8 +23,74 @@ The Hellō MCP server provides a **single powerful tool** (`hello_manage_app`) t - Secure OAuth 2.1 flow with short-lived access tokens - Supports both HTTP (remote) and STDIO (local) configurations - Access resources such as the Logo Design Guide, Login Button Guide, Quickstart Setup, and full API documentation +*/} + +## Installing + +### Cursor + + + + Install MCP Server + + +**Manual Install**: +Cursor Settings → MCP → Add new MCP Server. Use type `http` and URL `https://mcp.hello.coop/`. +See [Cursor guide](https://docs.cursor.com/context/mcp#installing-mcp-servers) for more information. + +### VSCode + + + + Install on VS Code + + +**Manual Install**: + +```bash +code --add-mcp '{"name":"Hellō Admin","url":"https://mcp.hello.coop","type":"http"}' +``` + +See [VS Code guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) for more information. + + +### Claude Code + +Using the Claude CLI: + +```bash +claude mcp add hello-admin http https://mcp.hello.coop/ +``` + +See [Claude guide](https://docs.anthropic.com/en/docs/claude-code/mcp) for more information. + +### Claude Desktop +??? + +### Gemini CLI +??? + +### Goose + + + Install in Goose + -## Getting Started +**Manual Install**: +Advanced settings → Extensions → Add custom extension and paste the [HTTP config](@ROHAN). +See [Goose guide](@ROHAN) for more information. + +### LM Studio + + + Add MCP Server hello-admin to LM Studio + + +**Manual Install**: +Program → Install → Edit mcp.json and paste the [HTTP config](@ROHAN). +See [LM Studio](@ROHAN) for more information. + +----------- You can install the Hellō MCP server manually using a simple configuration object, or use one of the quick-install options available in select tools. @@ -61,81 +125,6 @@ Use the following configurations if you're setting up the MCP server manually or ### Quick Installation Options Some tools support direct install links or commands that preconfigure the MCP server for you. -
-Cursor - -
-Click to install: - - - Install MCP Server - - -Or install manually via `Cursor Settings → MCP → Add new MCP Server`. Use type `http` and URL `https://mcp.hello.coop/`. - -
-
- -
-VS Code - -
-Click to install: - - - Install on VS Code - - -Or follow the [VS Code guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) or run: - -```bash -code --add-mcp '{"name":"Hellō Admin","url":"https://mcp.hello.coop","type":"http"}' -``` - -
-
- -
-Claude Code - -
-Install using the Claude CLI: - -```bash -claude mcp add hello-admin http https://mcp.hello.coop/ -``` - -
-
- -
-Claude Desktop - -

Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), and use the HTTP Transport config.

- -
- -
-Gemini CLI - -

See the [Gemini MCP Server docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson).

- -
- -
-Goose - -
-Click to install: - - - Install in Goose - - -Or go to `Advanced settings → Extensions → Add custom extension` and enter the HTTP config manually. - -
-
LM Studio @@ -172,6 +161,7 @@ Or go to `Program → Install → Edit mcp.json` and paste the standard config. Don’t see your tool listed? [File an issue](https://github.com/hellocoop/hello.dev/issues) and we’ll add support. ## Available Commands +KEY FEATURES ### `hello_manage_app` (Core Tool) @@ -204,6 +194,8 @@ This MCP server uses OAuth 2.1 for secure authentication: ## Troubleshooting +PRE REQUSITIES + ### Common Issues **"Authentication required" errors:** From e8e718e6a2ca8742479acacca960e03f6e5ae750 Mon Sep 17 00:00:00 2001 From: rohanharikr Date: Fri, 25 Jul 2025 22:03:13 +0100 Subject: [PATCH 7/8] Refine Admin MCP documentation for clarity and completeness - Remove commented-out key features section for a cleaner presentation - Update installation instructions for various tools with specific transport config details - Enhance troubleshooting section with common issues and solutions - Add new installation guidance for Qodo Gen and clarify manual configuration steps - Streamline security and limitations section for better readability --- pages/docs/admin-mcp.mdx | 132 +++++++++++++++------------------------ 1 file changed, 50 insertions(+), 82 deletions(-) diff --git a/pages/docs/admin-mcp.mdx b/pages/docs/admin-mcp.mdx index 1017178..3f8325b 100644 --- a/pages/docs/admin-mcp.mdx +++ b/pages/docs/admin-mcp.mdx @@ -13,18 +13,6 @@ including uploading logos for both light and dark themes. This MCP server is currently in BETA. Help us improve the server by filing [issues or making suggestions](https://github.com/hellocoop/MCP/issues). -{/* -## Key Features - -- One powerful tool (`hello_manage_app`) for all app management actions -- Supports `create`, `update`, `read`, `create_secret`, and logo uploads -- Compatible with major AI clients: Cursor, Claude, VS Code, LM Studio, and more -- Automatically includes full developer context (user, teams, applications) -- Secure OAuth 2.1 flow with short-lived access tokens -- Supports both HTTP (remote) and STDIO (local) configurations -- Access resources such as the Logo Design Guide, Login Button Guide, Quickstart Setup, and full API documentation -*/} - ## Installing ### Cursor @@ -65,10 +53,14 @@ claude mcp add hello-admin http https://mcp.hello.coop/ See [Claude guide](https://docs.anthropic.com/en/docs/claude-code/mcp) for more information. ### Claude Desktop -??? +**Manual Install**: +Navigate to Connector Settings → Add a Custom Connector → Paste the [HTTP Transport config](#manual). +See [Claude Desktop Guide](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server) for more information. ### Gemini CLI -??? +**Manual Install**: +Create `.gemini/settings.json` in your project's root directory → Add `mcpServers` block → Paste the [HTTP Transport config](#manual). +See [Gemini CLI Guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson) for more information. ### Goose @@ -77,8 +69,8 @@ See [Claude guide](https://docs.anthropic.com/en/docs/claude-code/mcp) for more **Manual Install**: -Advanced settings → Extensions → Add custom extension and paste the [HTTP config](@ROHAN). -See [Goose guide](@ROHAN) for more information. +Advanced settings → Extensions → Add custom extension and paste the [HTTP Transport config](#manual). +See [Example guide](https://docs.pieces.app/products/mcp/goose) for more information. ### LM Studio @@ -87,20 +79,27 @@ See [Goose guide](@ROHAN) for more information. **Manual Install**: -Program → Install → Edit mcp.json and paste the [HTTP config](@ROHAN). -See [LM Studio](@ROHAN) for more information. +Program → Install → Edit mcp.json and paste the [HTTP Transport config](#manual). +See [LM Studio](https://lmstudio.ai/blog/lmstudio-v0.3.17#add-mcp-servers-to-lm-studio) for more information. + +### Qodo Gen ------------ +**Manual Install**: +Open the chat panel → Connect more tools → Add new MCP → Paste the [Stdio Transport config](#manual) config. +See [Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen/qodo-gen-chat/agentic-mode/agentic-tools-mcps#id-1.-local-mcps) for more information. + +--- -You can install the Hellō MCP server manually using a simple configuration object, or use one of the quick-install options available in select tools. +Don’t see your tool listed? [File an issue](https://github.com/hellocoop/hello.dev/issues) and we’ll add support. -### Manual Configuration (Works in Most Tools) -> Using a supported tool like Cursor or VS Code? You can skip ahead to the Quick Installation Options below. +--- -Use the following configurations if you're setting up the MCP server manually or using a tool that prompts for input. +### Manual -**HTTP Transport (Remote – Recommended)** +**From Source**: +Clone the repo and follow the instructions at [hellocoop/MCP](https://github.com/hellocoop/MCP#local-development). +**HTTP Transport (Remote - Recommended)**: ```json { "hello-admin-http": { @@ -108,10 +107,9 @@ Use the following configurations if you're setting up the MCP server manually or "type": "http" } } -```` - -**NPM Package (Local)** +``` +**NPM Package (Local - Most compatible)**: ```json { "hello-admin-stdio": { @@ -122,48 +120,10 @@ Use the following configurations if you're setting up the MCP server manually or } ``` -### Quick Installation Options -Some tools support direct install links or commands that preconfigure the MCP server for you. - - -
-LM Studio - -
-Click to install: - - Add MCP Server hello-admin to LM Studio - - -Or go to `Program → Install → Edit mcp.json` and paste the standard config. - -
-
- -
-Qodo Gen - -

In Qodo Gen: open the chat panel → Connect more tools → Add new MCP → Paste the HTTP Transport config.

- -
- -
-Windsurf -

Follow the [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp). Use the standard config.

-
- -
-Run from Source -

Clone the repo and follow the instructions at: https://github.com/hellocoop/MCP#local-development

-
- -Don’t see your tool listed? [File an issue](https://github.com/hellocoop/hello.dev/issues) and we’ll add support. +## Features -## Available Commands -KEY FEATURES - -### `hello_manage_app` (Core Tool) +### `hello_manage_app` This is the primary tool for managing Hellō applications. @@ -183,7 +143,7 @@ Each response includes: * All apps associated with your teams * Current team and app state -## Authentication +### Authentication This MCP server uses OAuth 2.1 for secure authentication: @@ -192,12 +152,32 @@ This MCP server uses OAuth 2.1 for secure authentication: 3. **Token**: The server receives a 1-hour access token 4. **Context**: All API calls return your complete developer context -## Troubleshooting +### Security & Limitations -PRE REQUSITIES +**Security:** +- OAuth 2.1 industry-standard authentication +- Short-lived tokens (1-hour expiration) +- HTTPS-only API communication +- Access scoped to create, read, update. Deletion actions are intentionally restricted. + +**Current Limitations:** +- Cannot delete applications (use [Hellō Console](https://console.hello.coop) for deletion) +- Token requires re-authentication after 1 hour of inactivity + +## Troubleshooting ### Common Issues +**"npx command not found" error:** +- Install Node.js 18+ from [nodejs.org](https://nodejs.org/) +- Verify installation: `node --version` and `npm --version` +- On macOS/Linux, you may need to restart your terminal after installation + +**"MCP server not found" error:** +- Ensure your MCP client supports the transport type (HTTP or stdio) +- Check that the server URL or command is correctly configured +- Verify network connectivity for HTTP transport + **"Authentication required" errors:** - The server will automatically prompt for login when needed - Make sure you complete the browser-based OAuth flow @@ -220,18 +200,6 @@ PRE REQUSITIES - **Contribute**: [Submit Pull Requests](https://github.com/hellocoop/MCP/pulls) - **Community**: [Join our Slack Community](https://hello-community.slack.com/join/shared_invite/zt-1eccnd2np-qJoOWBkHGnpxvBpCTtaH9g#/shared-invite/email) -## Security & Limitations - -**Security:** -- OAuth 2.1 industry-standard authentication -- Short-lived tokens (1-hour expiration) -- HTTPS-only API communication -- Access scoped to create, read, update. Deletion actions are intentionally restricted. - -**Current Limitations:** -- Cannot delete applications (use [Hellō Console](https://console.hello.coop) for deletion) -- Token requires re-authentication after 1 hour of inactivity - --- For local development, testing, and advanced usage, visit the full [MCP Server GitHub repo](https://github.com/hellocoop/MCP). From 06dde5ee6980a45527d4f3a8e038771e7cb82f4d Mon Sep 17 00:00:00 2001 From: dickhardt Date: Sun, 27 Jul 2025 19:10:08 +0100 Subject: [PATCH 8/8] Update admin-mcp documentation: change mcp.hello.coop to admin-mcp.hello.coop and fix logo action names - Changed all references from mcp.hello.coop to admin-mcp.hello.coop - Updated NPM package name from @hellocoop/mcp to @hellocoop/admin-mcp - Fixed logo action names from upload_logo_file/upload_logo_url to update_logo_from_data/update_logo_from_url to match mcp_tools.js - Updated all deeplink URLs for Cursor, VSCode, Claude, Goose, and LM Studio --- pages/docs/admin-mcp.mdx | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/pages/docs/admin-mcp.mdx b/pages/docs/admin-mcp.mdx index 3f8325b..3d27f08 100644 --- a/pages/docs/admin-mcp.mdx +++ b/pages/docs/admin-mcp.mdx @@ -18,25 +18,25 @@ This MCP server is currently in BETA. Help us improve the server by filing [issu ### Cursor - + Install MCP Server **Manual Install**: -Cursor Settings → MCP → Add new MCP Server. Use type `http` and URL `https://mcp.hello.coop/`. +Cursor Settings → MCP → Add new MCP Server. Use type `http` and URL `https://admin-mcp.hello.coop/`. See [Cursor guide](https://docs.cursor.com/context/mcp#installing-mcp-servers) for more information. ### VSCode - + Install on VS Code **Manual Install**: ```bash -code --add-mcp '{"name":"Hellō Admin","url":"https://mcp.hello.coop","type":"http"}' +code --add-mcp '{"name":"Hellō Admin","url":"https://admin-mcp.hello.coop","type":"http"}' ``` See [VS Code guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) for more information. @@ -47,7 +47,7 @@ See [VS Code guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers# Using the Claude CLI: ```bash -claude mcp add hello-admin http https://mcp.hello.coop/ +claude mcp add hello-admin http https://admin-mcp.hello.coop/ ``` See [Claude guide](https://docs.anthropic.com/en/docs/claude-code/mcp) for more information. @@ -64,7 +64,7 @@ See [Gemini CLI Guide](https://github.com/google-gemini/gemini-cli/blob/main/doc ### Goose - + Install in Goose @@ -74,7 +74,7 @@ See [Example guide](https://docs.pieces.app/products/mcp/goose) for more informa ### LM Studio - + Add MCP Server hello-admin to LM Studio @@ -103,7 +103,7 @@ Clone the repo and follow the instructions at [hellocoop/MCP](https://github.com ```json { "hello-admin-http": { - "url": "https://mcp.hello.coop/", + "url": "https://admin-mcp.hello.coop/", "type": "http" } } @@ -114,7 +114,7 @@ Clone the repo and follow the instructions at [hellocoop/MCP](https://github.com { "hello-admin-stdio": { "command": "npx", - "args": ["-y", "@hellocoop/mcp@latest"], + "args": ["-y", "@hellocoop/admin-mcp@latest"], "type": "stdio" } } @@ -133,8 +133,8 @@ Supported actions: * `read` – Retrieve application or profile details * `update` – Update app settings (redirect URIs, names, etc.) * `create_secret` – Generate OAuth client secrets -* `upload_logo_file` – Upload a logo using base64 data -* `upload_logo_url` – Upload a logo via public URL +* `update_logo_from_data` – Upload a logo using base64 data +* `update_logo_from_url` – Upload a logo via public URL Each response includes: