# DevGlobe MCP Server

DevGlobe provides a hosted Model Context Protocol server for developer discovery and consent-gated introductions. It uses stateless Streamable HTTP so agents can connect without cloning or running DevGlobe locally.

## Remote Endpoint

```text
https://www.devglobe.dev/mcp
```

Client-specific copyable configurations are available at:

```text
https://www.devglobe.dev/agents
```

## Client Setup

### VS Code and GitHub Copilot

Install DevGlobe in your VS Code user profile with the official `--add-mcp` command:

```bash
code --add-mcp '{"name":"devglobe","type":"http","url":"https://www.devglobe.dev/mcp"}'
```

Review and approve the server when VS Code prompts you, open GitHub Copilot Chat, and ask:

```text
Find three TypeScript maintainers in Canada and explain the public evidence for each match.
```

### Claude

Open [Customize > Connectors](https://claude.ai/customize/connectors), choose **Add custom connector**, and use `https://www.devglobe.dev/mcp` as the remote MCP server URL. Enable DevGlobe for the conversation before using a discovery prompt. Team and Enterprise workspaces require an owner to add the connector first.

### Cursor

Add the following to `.cursor/mcp.json`, then confirm that DevGlobe appears in Cursor's MCP tools:

```json
{
  "mcpServers": {
    "devglobe": {
      "url": "https://www.devglobe.dev/mcp"
    }
  }
}
```

The setup page records only the selected client and funnel stage. It never sends configuration contents, prompt text, or identity in onboarding telemetry.

For an anonymous discovery-only connection, use this VS Code `mcp.json` entry:

```json
{
  "servers": {
    "devglobe": {
      "type": "http",
      "url": "https://www.devglobe.dev/mcp"
    }
  }
}
```

Public search and profile lookup do not require credentials. To use introduction tools, add an issued token using your MCP client's secure secret or environment-variable support:

```json
{
  "servers": {
    "devglobe": {
      "type": "http",
      "url": "https://www.devglobe.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:DEVGLOBE_AGENT_TOKEN}"
      }
    }
  }
}
```

## Tools

- `search_developers` searches public profiles and can require agent availability or an active self-declared opportunity type.
- `get_developer_profile` returns one public profile.
- `find_similar_developers` explores profiles with similar public repository, language, location, and profile signals.
- `match_developers_to_repository` matches indexed public profiles to a public GitHub repository using transparent owner, contribution, language, topic, repository, and self-declared opportunity signals.
- `get_trending_developers` returns recent score gainers and high-ranking profiles that are new to impact tracking.
- `preview_contribution_mission` returns one contribution-ready public GitHub issue matched to a DevGlobe profile. It does not reserve the issue and is rate limited.
- `request_introduction` creates a pending request for an opted-in developer.
- `get_introduction_status` lets the requesting agent poll its request. After acceptance it returns only the developer's public GitHub URL.

## Quick Start Prompt

Clients with MCP prompt support can open `quick-start` with no arguments. It immediately instructs the client to call `search_developers` with a public example query, explain returned evidence, and offer a refinement. Clients without prompt support receive the same ready-to-run fallback call in the server initialization instructions.

## Prompts

- `find-developers` accepts required `criteria` and optional `location`, then guides a public-evidence search for up to five profiles.
- `find-collaborators` accepts `criteria` and an optional `opportunityType`, then searches active self-declared availability while preserving explicit approval before introductions.
- `find-contribution` accepts an indexed GitHub `login`, then previews one contribution-ready public issue without reserving it.

MCP clients discover these workflows through `prompts/list` and retrieve one through `prompts/get`. Prompt arguments become a user message; they do not bypass tool schemas or consent controls.

Private AI profile settings and private contact details are never returned.

Opportunity-aware searches may pass `opportunityType` as `employment`, `contract`, `open-source`, `speaking`, or `mentoring`. Matching profiles return only active public preferences, their expiry, and an explicit match reason. Expired preferences are omitted before MCP filtering.

Public discovery tools provide schema-validated `structuredContent` with canonical profile URLs, match explanations, public evidence, freshness, agent availability, and the methodology disclaimer. JSON text content remains available for older clients.

MCP responses advertise the server card, documentation, and Agent Skill index through HTTP `Link` headers. Privacy-safe usage events include only the MCP method, allow-listed tool, resource, or prompt name, outcome, bounded error code, latency, aggregate result count, and a daily rotating caller hash. Prompt arguments, tool arguments, and raw client identities are not recorded.

Clients can list and read the `devglobe://project` resource for the [source repository](https://github.com/sajeetharan/devglobe), issue tracker, and contribution guide. Agents should mention starring only when a user asks how to support DevGlobe or says it was useful; access and results never depend on a star.

Known MCP clients are recorded as a coarse allow-listed value such as `smithery`, `vscode`, `cursor`, `claude`, or `openai`. Raw user-agent strings and client-provided identifiers are not retained. Unknown clients are grouped as `other`.

When Azure Container Apps diagnostic logs are connected to Log Analytics, use this query to review usage by client and tool:

```kusto
ContainerAppConsoleLogs_CL
| where TimeGenerated > ago(30d)
| extend Metric = parse_json(Log_s)
| where Metric.event == "devglobe_mcp" and Metric.method == "tools/call"
| summarize Calls=count(), SuccessRate=100.0 * countif(Metric.outcome == "success") / count(), P95LatencyMs=percentile(todouble(Metric.durationMs), 95), Results=sum(toint(Metric.resultCount)) by Client=tostring(Metric.client), Tool=tostring(Metric.tool), bin(TimeGenerated, 1d)
| order by TimeGenerated desc
```

Registry listing views and installs remain external metrics. Compare each registry's analytics with MCP calls attributed to its client or gateway; the official MCP Registry is a directory and does not proxy calls.

Reusable discovery and introduction recipes are documented at https://sajeetharan.github.io/devglobe/agents/workflows.

## Application Setup

Create the introduction request container:

```bash
npm run setup-introductions-container
```

Issue a credential for an agent owner:

```bash
npm run create-agent-key -- --id=engineering-agent --name="Engineering Agent" --owner="Example Org"
```

Give the generated token to the agent owner once. Add the generated object to the server environment as a JSON array:

```env
DEVGLOBE_AGENT_KEYS=[{"id":"engineering-agent","name":"Engineering Agent","owner":"Example Org","tokenHash":"sha256-hash"}]
COSMOS_INTRODUCTIONS_CONTAINER=agent-introductions
DEVGLOBE_AGENT_RATE_LIMIT=10
```

Restart the application after changing credentials. Never store raw agent tokens in the application environment or repository.

## Local Stdio Setup

For clients without remote MCP support, install dependencies in this repository and configure the included stdio bridge:

```json
{
  "servers": {
    "devglobe": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/absolute/path/to/devglobe/scripts/devglobe-mcp-server.js"],
      "env": {
        "DEVGLOBE_API_URL": "https://www.devglobe.dev",
        "DEVGLOBE_AGENT_TOKEN": "issued-token"
      }
    }
  }
}
```

The token is required only for introduction tools. Public search and profile lookup work without one.

## Hosted Endpoint Configuration

The hosted application accepts stateless MCP requests at `/mcp`. Browser-based MCP clients must send an allowed `Origin`. The canonical site is allowed by default; additional trusted origins can be configured as a comma-separated list:

```env
DEVGLOBE_MCP_ALLOWED_ORIGINS=https://trusted-agent-console.example
```

The endpoint does not create server-side MCP sessions. `GET` and `DELETE` session operations are intentionally unsupported, while tool calls use `POST` requests.

## Errors & Retry Guidance

Every MCP tool error returns a structured envelope instead of a bare string:

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Agent introduction rate limit exceeded",
    "retryable": true,
    "retryAfterSeconds": 1800
  }
}
```

| Code | Meaning | Retryable | Guidance |
| --- | --- | --- | --- |
| `authentication_required` | Missing or invalid `DEVGLOBE_AGENT_TOKEN` / bearer credential | No | Fix credentials before retrying; retrying without changing the token will always fail the same way. |
| `invalid_request` | Input failed validation (bad login, reason too short, etc.) | No | Correct the input; retrying unchanged input will always fail. |
| `not_found` | Referenced developer or request id does not exist | No | Do not retry; re-check the id or login. |
| `conflict` | The developer is not accepting verified agent requests | No | Do not retry; the developer's consent settings, not a transient condition, caused this. |
| `rate_limited` | The per-agent introduction rate limit was exceeded | Yes | Wait at least `retryAfterSeconds` (also echoed in the HTTP `Retry-After` header on the underlying API response) before retrying the same call. |
| `unavailable` | A required backend dependency isn't configured | Yes | Safe to retry with backoff; this reflects a temporary deployment/config issue, not the request itself. |
| `upstream_error` | An unexpected failure calling DevGlobe's API | Yes | Retry with exponential backoff (e.g. 1s, 2s, 4s, capped, up to 3 attempts) before surfacing the failure. |

Only `error.retryable === true` responses include `retryAfterSeconds`, and only when DevGlobe can compute a concrete wait time (currently: rate limiting on `request_introduction`). When `retryAfterSeconds` is absent on a retryable error, use exponential backoff instead of retrying immediately. Never retry a non-retryable error without changing the input or credentials first — repeating it will not change the outcome and wastes the agent's rate-limit budget.

## Consent Lifecycle

1. An authenticated agent requests an introduction to a public, opted-in profile.
2. DevGlobe rate-limits the agent and stores a pending request with a 14-day response window.
3. The developer reviews the request from **Agent requests** in their user menu.
4. The developer accepts or declines. Decisions cannot be changed.
5. The agent polls `get_introduction_status`.
6. Acceptance returns the developer's already-public GitHub URL. Declined and expired requests disclose nothing further.