Developer Knowledge Retrieval Transport Mechanisms: MCP and REST API

The google/skills repository provides two transport mechanisms for Developer Knowledge Retrieval: a preferred Model Context Protocol (MCP) using standard-input/standard-output (stdio) transport, and a REST API fallback over HTTPS with multiple authentication strategies.

The Developer Knowledge Retrieval system enables access to official Google documentation through dual transport architectures designed for different operational contexts. Implemented in the google/skills repository, these mechanisms prioritize low-latency local execution while maintaining universal accessibility through standard HTTP endpoints. Understanding both transports ensures resilient documentation retrieval across diverse deployment environments.

Developer Knowledge MCP Transport (Preferred)

The Model Context Protocol (MCP) transport represents the primary mechanism for Developer Knowledge Retrieval when an MCP client is available in the local environment.

MCP stdio Transport Architecture

According to the implementation in plugins/cloud/google-cloud-developer/skills/retrieving-developer-knowledge/references/mcp-usage.md, the MCP server communicates with the client via standard-input/standard-output (stdio) transport. This architecture runs locally within the same process as the skill, eliminating external HTTP dependencies while providing binary-safe communication. The stdio transport delivers sub-second latency and requires no network port configuration or firewall exceptions.

Available MCP Tool Calls

The MCP client exposes three distinct tool calls for documentation retrieval:

• answer_query(query="…") – Retrieves conceptual guides, architectural comparisons, and multi-step workflows
• search_documents(query="…", page_size=…) – Locates granular technical details such as CLI flags, API syntax, and IAM permission strings
• get_documents(names=["documents/{uri_without_scheme}"]) – Fetches complete documentation pages by specific resource identifiers

MCP Implementation Example

When the MCP client is available, invoke the tools directly from your skill implementation:

# Example: invoke the MCP answer_query tool from a skill implementation

answer = answer_query(query="How does Cloud Run handle traffic splitting?")
print(answer)   # The tool returns the official documentation fragment

REST API Fallback Transport

When MCP tools are unavailable or cannot complete the handshake, the system automatically falls back to the Developer Knowledge REST API.

HTTPS Endpoint and Authentication

As documented in plugins/cloud/google-cloud-developer/skills/retrieving-developer-knowledge/references/api-fallback.md, the REST transport communicates over HTTPS using the public endpoint https://developerknowledge.googleapis.com/v1. The implementation attempts two credential strategies in strict order:

1. Google-auth token – Uses tokens from gcloud auth print-access-token or gcloud auth application-default print-access-token
2. API key – Uses the DEVELOPERKNOWLEDGE_API_KEY environment variable passed as a query parameter

This HTTPS transport functions with any standard HTTP client or curl, ensuring universal compatibility across programming languages and environments.

REST API with Google Authentication

Retrieve documentation using an OAuth 2.0 bearer token from gcloud:

# Retrieve a conceptual answer via the REST API

curl -s -X POST "https://developerknowledge.googleapis.com/v1:answerQuery" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "X-Goog-User-Project: $(gcloud config get-value project 2>/dev/null)" \
  -H "Content-Type: application/json" \
  -d '{"query":"How does Cloud Run handle traffic splitting?"}'

REST API with API Key Authentication

For environments without gcloud authentication, use an API key:

# Same request, using an API key instead of a bearer token

curl -s -X POST "https://developerknowledge.googleapis.com/v1:answerQuery?key=${DEVELOPERKNOWLEDGE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"query":"How does Cloud Run handle traffic splitting?"}'

Transport Selection and Error Handling

The logical flow for Developer Knowledge Retrieval follows a consistent pattern across both transports as defined in skills/developers/retrieving-developer-knowledge/SKILL.md. The system first attempts MCP communication, verifies the response for error conditions including PERMISSION_DENIED, UNAUTHENTICATED, or empty results, then automatically falls back to the REST API if the initial attempt fails. This dual-path approach ensures documentation availability even when local MCP servers are offline or misconfigured.

Source File References

The transport implementations are documented in the following key files within the google/skills repository:

• skills/developers/retrieving-developer-knowledge/SKILL.md – Defines the overall workflow, transport selection logic, and usage guidelines
• plugins/cloud/google-cloud-developer/skills/retrieving-developer-knowledge/references/mcp-usage.md – Details the MCP server configuration and stdio transport mechanism
• plugins/cloud/google-cloud-developer/skills/retrieving-developer-knowledge/references/api-fallback.md – Describes the REST API endpoints, authentication options, and example curl commands

Summary

• Dual transport architecture: Developer Knowledge Retrieval supports MCP (preferred) and REST API (fallback) mechanisms
• MCP stdio transport: Provides low-latency, binary-safe local communication without external HTTP dependencies
• Three MCP tools: answer_query, search_documents, and get_documents handle different documentation retrieval scenarios
• REST API endpoint: https://developerknowledge.googleapis.com/v1 accepts both Google-auth tokens and API keys
• Automatic fallback: The system attempts MCP first, then degrades gracefully to REST API on authentication or connection failures

Frequently Asked Questions

What is the difference between MCP and REST API transport for Developer Knowledge Retrieval?

The MCP transport uses local stdio communication for sub-second latency and requires no network configuration, while the REST API uses HTTPS requests to developerknowledge.googleapis.com for universal compatibility. The MCP transport is preferred when available, but the REST API serves as a reliable fallback when local MCP clients are unavailable.

How do I authenticate with the Developer Knowledge REST API?

The REST API supports two authentication methods: OAuth 2.0 bearer tokens from gcloud auth print-access-token (preferred for development), or API keys via the DEVELOPERKNOWLEDGE_API_KEY environment variable (suitable for automated environments). The system attempts Google authentication first, then falls back to API keys if the former fails.

What MCP tools are available for retrieving developer documentation?

The MCP implementation exposes three tools: answer_query for conceptual questions and workflows, search_documents for specific technical details like CLI flags, and get_documents for retrieving full documentation pages by URI. These tools are accessed through the stdio transport when the MCP client is present in the local process.

When should I use the REST API fallback instead of MCP?

Use the REST API fallback when running in environments without MCP client capabilities, such as containerized deployments without local stdio access, or when the MCP handshake fails due to permission errors (PERMISSION_DENIED) or authentication issues (UNAUTHENTICATED). The REST API requires only standard HTTPS egress and works with any HTTP client.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}