Skip to content

Hosted MCP: clearer server card and connection checks #203

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SyedFahad7 merged 2 commits into from
Nov 3, 2026
Merged

Hosted MCP: clearer server card and connection checks #203

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ccf59ae
Tidy the hosted MCP server card section
SyedFahad7 Nov 3, 2026
ab8397a
Explain the server card fields and merge the connection checks
SyedFahad7 Nov 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
156 changes: 113 additions & 43 deletions platform/hosted-mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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).

Expand Down Expand Up @@ -112,7 +112,7 @@ One-click installs: [Connect to Cursor](cursor://anysphere.cursor-deeplink/mcp/i
</Tab>
</Tabs>

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

Expand All @@ -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:
Expand All @@ -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` |
<Columns cols={2}>
<Card title="Server card" icon="id-card">
`https://api.graphify.com/mcp/server-card`. Who the server is and where to reach it.
</Card>
<Card title="AI catalog" icon="list">
`https://api.graphify.com/.well-known/ai-catalog.json`. Lists the server card, so a client that only knows the domain can find it.
</Card>
</Columns>

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:
<Steps>
<Step title="Find the card">
A client or registry reads the AI catalog at `api.graphify.com`, or goes straight to the server card.
</Step>
<Step title="Set up the connection">
It reads the name, icon and remote URL from the card and adds Graphify for you.
</Step>
<Step title="Sign in and list tools">
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`.
</Step>
</Steps>

```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.

<AccordionGroup>
<Accordion title="Why doesn't the card list Graphify's tools?">
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.
</Accordion>
<Accordion title="Why is there no key or header in the card?">
Sign-in uses OAuth. The client finds the sign-in flow from the server's `401` response, so the card needs no credentials.
</Accordion>
<Accordion title="Can a web app read the card?">
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.
</Accordion>
<Accordion title="How do I check the 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.
</Accordion>
</AccordionGroup>

### 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

Expand Down Expand Up @@ -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.
<Steps>
<Step title="Check the client shows Graphify">
Your client should list `graphify` as connected, with its tools.
</Step>
<Step title="List what you can see">
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.
</Step>
<Step title="Ask about code you know">
Pick an indexed repository, ask about a function you know, then ask for its callers or tests. Check the evidence against the code.
</Step>
</Steps>

| 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

<AccordionGroup>
<Accordion title="The client shows &quot;needs authentication&quot;">
Run the client's sign-in step: `/mcp` → Authenticate, or `codex mcp login graphify`.
</Accordion>
<Accordion title="list_repositories is empty">
You're in a workspace with no indexed repositories. Switch with `set_workspace`.
</Accordion>
<Accordion title="A repository returns no results">
Check in Graphify that it finished indexing, and that you're in the right workspace (`list_workspaces`).
</Accordion>
<Accordion title="Tools connect but chat can't run them">
Turn the tools on in your client and check that your model can call tools. In Copilot, add `"tools": ["*"]` to its config.
</Accordion>
<Accordion title="Graphify isn't in my client's MCP gallery">
Add `https://api.graphify.com/mcp` directly. The MCP Registry listing (`io.github.Graphify-Labs/graphify`) and gallery inclusion are separate.
</Accordion>
<Accordion title="npx or Node.js isn't found">
Install Node.js where the client can find it, or use the client's native remote setup.
</Accordion>
<Accordion title="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.
</Accordion>
<Accordion title="Does the hosted MCP see my local changes?">
No. It serves the indexed graph. For uncommitted work, use the [local MCP server](/open-source/mcp-server).
</Accordion>
Expand All @@ -251,7 +321,7 @@ Seeing the tools doesn't prove repository access. Step 4 does. For test prompts

<Columns cols={2}>
<Card title="Ask" icon="comments" href="/platform/ask">
The same graph, in the Console.
The same graph, in the Graphify app.
</Card>
<Card title="Memory" icon="brain" href="/platform/memory">
What your agents remember.
Expand Down
2 changes: 1 addition & 1 deletion platform/verify-connection.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ Then ask a code question without naming Graphify, such as `What calls <function>
| 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

Expand Down
Loading