diff --git a/platform/hosted-mcp.mdx b/platform/hosted-mcp.mdx
index f9493bf..960aa3e 100644
--- a/platform/hosted-mcp.mdx
+++ b/platform/hosted-mcp.mdx
@@ -2,14 +2,14 @@
title: "Hosted MCP server for code graphs, with OAuth"
sidebarTitle: "Hosted MCP"
description: "Connect Claude Code, Cursor, Codex, or VS Code to Graphify's hosted MCP server with OAuth sign-in. Tools, workspaces, 240/min limit, errors."
-keywords: ["graphify mcp", "hosted mcp server", "mcp oauth", "code graph mcp", "claude code mcp", "cursor mcp", "codex mcp"]
+keywords: ["graphify mcp", "hosted mcp server", "mcp oauth", "code graph mcp", "claude code mcp", "cursor mcp", "codex mcp", "remote mcp server", "mcp server card", "mcp registry"]
surface: "cloud"
icon: "cloud"
---
import TryCloudCard from '/snippets/try-cloud-card.mdx';
-The **hosted MCP** server gives your coding agent the same graph you see in the Console. Instead of grepping through files, your agent asks Graphify for the entities, relationships, and paths it needs, and gets grounded answers for a fraction of the tokens.
+The **hosted MCP** server gives your coding agent the same graph you see in the Graphify app. Instead of grepping through files, your agent asks Graphify for the entities, relationships, and paths it needs, and gets grounded answers for a fraction of the tokens.
```text
https://api.graphify.com/mcp
@@ -29,7 +29,7 @@ You sign in with OAuth from your client. There's no API key to paste.
## Connect your client
-The **MCP** tab under **Connectors** in the Console shows the setup for your client, with your endpoint filled in.
+The **MCP** tab under **Connectors** in Graphify shows the setup for your client, with your endpoint filled in.
One-click installs: [Connect to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=graphify&config=eyJ1cmwiOiJodHRwczovL2FwaS5ncmFwaGlmeS5jb20vbWNwIn0%3D), the [Graphify extension for VS Code](https://marketplace.visualstudio.com/items?itemName=graphify-labs.graphify-mcp), or the [Graphify plugin for ChatGPT and Codex](https://chatgpt.com/plugins/plugin_asdk_app_6abe89f7f5d88191b9422522bb8562a4).
@@ -112,7 +112,7 @@ One-click installs: [Connect to Cursor](cursor://anysphere.cursor-deeplink/mcp/i
-The Console also has setup for VS Code, Windsurf, Cline, Continue, JetBrains, Zed, Goose, Kiro, and other clients, including one-click install links where a client supports them.
+Graphify also has setup for VS Code, Windsurf, Cline, Continue, JetBrains, Zed, Goose, Kiro, and other clients, including one-click install links where a client supports them.
### Clients without remote OAuth
@@ -139,16 +139,6 @@ Add `?repo=` with the repository's full name to set a default:
https://api.graphify.com/mcp?repo=acme/payments
```
-## Test the connection
-
-Ask your agent:
-
-```text
-Use Graphify's list_repositories tool and show the repositories I can access. If the tool fails, report the error instead of guessing.
-```
-
-If you belong to several workspaces, ask it to run `list_workspaces`, then `set_workspace` with the one you want.
-
## What your agent can do
Your client builds its tool list from the server's `tools/list` response, so the client's tool panel always shows the current set. The repository tools, such as `list_repositories`, come from the indexed graph. Graphify adds two workspace tools to every session:
@@ -171,22 +161,79 @@ You don't paste a key. Your client discovers the sign-in flow from the server:
If a token doesn't verify, you get the same discovery `401`, and your client starts the sign-in again.
-## Server card
+## Let clients find Graphify with a server card
-Graphify publishes an [MCP Server Card](https://modelcontextprotocol.io/seps/2127-mcp-server-cards). It's a public JSON document that tells a client where the server is and how to connect, before the client connects. Clients, registries and IDE extensions that support server cards can set up Graphify from it.
+**Your client can find Graphify on its own.** Graphify publishes an [MCP server card](https://modelcontextprotocol.io/seps/2127-mcp-server-cards): a small public JSON file that says what the server is and where to connect. A client can read it before it connects or signs in, so you don't have to type the server URL.
-| Document | URL |
-| --- | --- |
-| Server card | `https://api.graphify.com/mcp/server-card` |
-| AI Catalog that lists it | `https://api.graphify.com/.well-known/ai-catalog.json` |
+
+
+ `https://api.graphify.com/mcp/server-card`. Who the server is and where to reach it.
+
+
+ `https://api.graphify.com/.well-known/ai-catalog.json`. Lists the server card, so a client that only knows the domain can find it.
+
+
-The card names the server `io.github.Graphify-Labs/graphify`, as in the MCP Registry, and lists one remote: `https://api.graphify.com/mcp` over Streamable HTTP. It doesn't list tools. Your client still gets those from `tools/list` after you sign in, because they depend on your workspace.
+### When a client uses it
-To check the card yourself:
+
+
+ A client or registry reads the AI catalog at `api.graphify.com`, or goes straight to the server card.
+
+
+ It reads the name, icon and remote URL from the card and adds Graphify for you.
+
+
+ It connects to `https://api.graphify.com/mcp`, runs the [OAuth sign-in](#how-hosted-mcp-sign-in-works), then gets your tools from `tools/list`.
+
+
-```bash
-curl -H "Accept: application/mcp-server-card+json" https://api.graphify.com/mcp/server-card
-```
+Clients that don't read server cards keep working with the setup steps above.
+
+### What's in the card
+
+| Field | Value | What it's for |
+| --- | --- | --- |
+| `name` | `io.github.Graphify-Labs/graphify` | Unique ID. Matches the MCP Registry entry. |
+| `title` | `Graphify` | The name a client shows you. |
+| `description` | What the server does | Shown next to the name. |
+| `version` | Version number, such as `0.1.1` | Which release of the listing this is. |
+| `remotes` | `streamable-http` at `https://api.graphify.com/mcp` | Where and how to connect. |
+| `icons` | 400×400 PNG logo | The icon a client shows. |
+| `websiteUrl` | `https://graphify.com/mcp` | Where to learn more. |
+| `repository` | `github.com/Graphify-Labs/graphify-mcp` | Where the server code lives. |
+
+The AI catalog has one entry, `urn:air:graphify.com:mcp:graphify`, of type `application/mcp-server-card+json`, pointing at the server card.
+
+
+
+ Your tools depend on your workspace, so a public file can't list them. Your client gets them from `tools/list` after you sign in.
+
+
+ Sign-in uses OAuth. The client finds the sign-in flow from the server's `401` response, so the card needs no credentials.
+
+
+ Yes. The card and catalog allow any origin (`Access-Control-Allow-Origin: *`), are cached for an hour, and send an `ETag`. Send it back in `If-None-Match` and you get `304 Not Modified` if nothing changed.
+
+
+ ```bash
+ curl -H "Accept: application/mcp-server-card+json" https://api.graphify.com/mcp/server-card
+ ```
+
+ You get back JSON with the server's name and remote URL.
+
+
+
+### Other discovery endpoints
+
+These public files tell a client how to sign in. Your client reads them for you.
+
+| Endpoint | What it describes |
+| --- | --- |
+| `/.well-known/oauth-protected-resource/mcp` | The MCP server, its sign-in server and the `graphify:query` scope. |
+| `/.well-known/oauth-authorization-server` | Sign-in, token, registration and revoke URLs, with PKCE (`S256`). Also at `/.well-known/openid-configuration`. |
+
+All are on `https://api.graphify.com` and are cached for an hour.
## Workspaces and MCP sessions
@@ -219,29 +266,52 @@ Every request runs in one workspace. Graphify picks it in this order: the worksp
The request limit is counted per client IP address for signed-in sessions. Over the limit returns `429 rate_limited`. A request body over 256 KB returns `413 mcp_body_too_large`. See [Rate limits](/platform/support/rate-limits).
-## Verify the connection
+## Check the connection
-1. Check that your client shows `graphify` as connected and lists its tools.
-2. Ask it to list your workspaces and repositories.
-3. Pick an indexed repository and ask about a function you know.
-4. Ask for that function's callers or tests, and check the evidence it returns against the code.
+
+
+ Your client should list `graphify` as connected, with its tools.
+
+
+ Ask your agent:
-Seeing the tools doesn't prove repository access. Step 4 does. For test prompts and fixes per client, see [Check your agent is using Graphify](/platform/verify-connection).
+ ```text
+ Use Graphify's list_repositories tool and show the repositories I can access. If the tool fails, report the error instead of guessing.
+ ```
-## Verify and troubleshoot
+ If you belong to several workspaces, ask it to run `list_workspaces`, then `set_workspace` with the one you want.
+
+
+ Pick an indexed repository, ask about a function you know, then ask for its callers or tests. Check the evidence against the code.
+
+
-| Symptom | Fix |
-| --- | --- |
-| Client shows "needs authentication" | Run the client's sign-in step (`/mcp` → Authenticate, or `codex mcp login graphify`). |
-| `list_repositories` is empty | You're in a workspace with no indexed repositories. Use `set_workspace`. |
-| Copilot connects but has no tools | Add `"tools": ["*"]` to its config. |
-| Server isn't in a client's MCP gallery | Add `https://api.graphify.com/mcp` directly. Registry listing (`io.github.Graphify-Labs/graphify`) and gallery inclusion are separate. |
-| `npx` or Node.js not found | Install Node.js where the client can find it, or use the native remote setup. |
-| Tools connect but chat can't run them | Turn the tools on in your client and check that your model can call tools. |
-| No results from a repository | Check that it finished indexing in the Console, and that you're in the right workspace (`list_workspaces`). |
-| Copilot on github.com can't connect | Copilot's coding agent and code review only support static header credentials, not OAuth sign-in, so they can't use this endpoint yet. |
+Seeing the tools doesn't prove repository access. The last step does. For test prompts per client, see [Check your agent is using Graphify](/platform/verify-connection).
+
+### Fix common problems
+
+ Run the client's sign-in step: `/mcp` → Authenticate, or `codex mcp login graphify`.
+
+
+ You're in a workspace with no indexed repositories. Switch with `set_workspace`.
+
+
+ Check in Graphify that it finished indexing, and that you're in the right workspace (`list_workspaces`).
+
+
+ Turn the tools on in your client and check that your model can call tools. In Copilot, add `"tools": ["*"]` to its config.
+
+
+ Add `https://api.graphify.com/mcp` directly. The MCP Registry listing (`io.github.Graphify-Labs/graphify`) and gallery inclusion are separate.
+
+
+ Install Node.js where the client can find it, or use the client's native remote setup.
+
+
+ Copilot's coding agent and code review only support static header credentials, not OAuth sign-in, so they can't use this endpoint yet.
+
No. It serves the indexed graph. For uncommitted work, use the [local MCP server](/open-source/mcp-server).
@@ -251,7 +321,7 @@ Seeing the tools doesn't prove repository access. Step 4 does. For test prompts
- The same graph, in the Console.
+ The same graph, in the Graphify app.
What your agents remember.
diff --git a/platform/verify-connection.mdx b/platform/verify-connection.mdx
index 1e0fcc1..68b7cb2 100644
--- a/platform/verify-connection.mdx
+++ b/platform/verify-connection.mdx
@@ -55,7 +55,7 @@ Then ask a code question without naming Graphify, such as `What calls
| A Cursor cloud agent can't see Graphify | Cloud agents don't read your local `mcp.json`, and they keep their own sign-in. Add and sign in to Graphify for cloud agents at [cursor.com/agents](https://cursor.com/agents). |
| Answers miss today's changes | Graphify serves the indexed default branch. Uncommitted work isn't in it. |
-More fixes are in [Hosted MCP](/platform/hosted-mcp#verify-and-troubleshoot) and [Troubleshooting](/platform/support/troubleshooting).
+More fixes are in [Hosted MCP](/platform/hosted-mcp#fix-common-problems) and [Troubleshooting](/platform/support/troubleshooting).
## Prove it after a session