From ccf59ae49e88b23c1b0805ab53d90af41c99e5ab Mon Sep 17 00:00:00 2001 From: Syed Fahad <142882322+SyedFahad7@users.noreply.github.com> Date: Wed, 4 Nov 2026 03:22:20 +0530 Subject: [PATCH 1/2] Tidy the hosted MCP server card section Plainer heading, a short opener, cards for the two URLs and an accordion for common questions. --- platform/hosted-mcp.mdx | 40 ++++++++++++++++++++++++++++------------ 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/platform/hosted-mcp.mdx b/platform/hosted-mcp.mdx index f9493bf..2b106a6 100644 --- a/platform/hosted-mcp.mdx +++ b/platform/hosted-mcp.mdx @@ -2,7 +2,7 @@ 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" --- @@ -171,22 +171,38 @@ 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 where the server is and how to connect, so a client can read it before it signs in. -| 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`. The server's name, its URL and how to reach it. + + + `https://api.graphify.com/.well-known/ai-catalog.json`. Points clients at the server card from the domain. + + + +Clients, registries and editor extensions that support server cards can set Graphify up from these files. Other clients keep working with the setup steps above. -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. + + + The name `io.github.Graphify-Labs/graphify`, which matches the MCP Registry entry, and one remote: `https://api.graphify.com/mcp` over Streamable HTTP. There's no key or header in it, because sign-in uses OAuth. + + + No. The tools depend on your workspace, so your client gets them from `tools/list` after you sign in. + + + Run: -To check the card yourself: + ```bash + curl -H "Accept: application/mcp-server-card+json" https://api.graphify.com/mcp/server-card + ``` -```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. + + ## Workspaces and MCP sessions From ab8397aedb6d123e463d4c6186005e17f53b9005 Mon Sep 17 00:00:00 2001 From: Syed Fahad <142882322+SyedFahad7@users.noreply.github.com> Date: Wed, 4 Nov 2026 03:30:39 +0530 Subject: [PATCH 2/2] Explain the server card fields and merge the connection checks Say plain Graphify instead of the Console, list each card field, add the sign-in discovery endpoints, and fold three overlapping check sections into one. --- platform/hosted-mcp.mdx | 138 +++++++++++++++++++++++---------- platform/verify-connection.mdx | 2 +- 2 files changed, 97 insertions(+), 43 deletions(-) diff --git a/platform/hosted-mcp.mdx b/platform/hosted-mcp.mdx index 2b106a6..960aa3e 100644 --- a/platform/hosted-mcp.mdx +++ b/platform/hosted-mcp.mdx @@ -9,7 +9,7 @@ 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: @@ -173,29 +163,59 @@ If a token doesn't verify, you get the same discovery `401`, and your client sta ## Let clients find Graphify with a server card -**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 where the server is and how to connect, so a client can read it before it signs in. +**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. - `https://api.graphify.com/mcp/server-card`. The server's name, its URL and how to reach it. + `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`. Points clients at the server card from the domain. + `https://api.graphify.com/.well-known/ai-catalog.json`. Lists the server card, so a client that only knows the domain can find it. -Clients, registries and editor extensions that support server cards can set Graphify up from these files. Other clients keep working with the setup steps above. +### When a client uses it + + + + 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`. + + + +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. - - The name `io.github.Graphify-Labs/graphify`, which matches the MCP Registry entry, and one remote: `https://api.graphify.com/mcp` over Streamable HTTP. There's no key or header in it, because sign-in uses OAuth. + + 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. - - No. The tools depend on your workspace, so 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. - - Run: - + + 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 ``` @@ -204,6 +224,17 @@ Clients, registries and editor extensions that support server cards can set Grap +### 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 Every request runs in one workspace. Graphify picks it in this order: the workspace bound to this MCP session, then your default workspace, then your only workspace if you belong to just one. @@ -235,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). @@ -267,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